Files
hagrid/README.md
2025-09-29 22:37:55 +02:00

99 lines
6.3 KiB
Markdown

Hagrid
======
Hagrid is a verifying OpenPGP key server.
You can find general instructions and an API documentation at the running
instance at [https://keys.openpgp.org](https://keys.openpgp.org).
Please note that Hagrid is built and maintained only for the service at
keys.openpgp.org. It is not maintained or officially supported as
deployable software.
Compatibility note: Hagrid v2.0 uses an sqlite certificate store instead of the
previous file based database. This means that it also no longer supports serving
certificates directly via reverse proxy. You can us hagridctl to dump and import
an old database.
License
-------
Hagrid is free software: you can redistribute it and/or modify it
under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
Hagrid is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
License for more details.
You should have received a copy of the GNU Affero General Public
License along with Hagrid. If not, see
<https://www.gnu.org/licenses/>.
Quick Start
-----------
Building Hagrid requires a working stable Rust toolchain.
The easiest way to get the toolchain is to download [rustup](https://rustup.rs).
Additionally, some external dependencies are required.
Get them (on Debian or Ubuntu) with
```bash
sudo apt install gnutls-bin libssl-dev gcc llvm-dev libclang-dev build-essential pkg-config gettext libsqlite3-dev
```
After Rust and the other dependencies are installed, copy the config file (or run `just init`), then simply compile and run:
```bash
cd hagrid
cp Rocket.toml.dist Rocket.toml
cargo run
```
This will spawn a web server listening on port 8080.
For deployment, a release build should be used (`cargo build --release`). This
will be statically built, and can be copied anywhere. You will also need to
adjust `Rocket.toml` accordingly. Hagrid uses `sendmail` for mailing, so you
also need a working local mailer setup.
About Pages
-----------
The pages under /about are built using [zola](https://getzola.org). Templates
served by hagrid assume that the built pages are available under `/about`, but
they are independent from the rest of the code.
# Development Dependencies
List of dependencies which are required or could be helpful for contribution
to the project.
| Category | Type | Name | Version | Verified Version | Notes |
|:--------------------------------:|:-----------:|:------------------------------------------:|:----------:|:----------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Shell | Obligatory | [Zsh](https://zsh.sourceforge.io/) | \>= 5.9 | 5.9 | Required for [translated templates generation](./make-translated-templates) script. |
| VCS/SCM | Obligatory | [Git](https://git-scm.com/) | \>= 2.47.3 | 2.47.3 | Obviously, if going to get this repository you'll have the `git` CLI as dependency. But it also used in `just upgrade-rust` recipe to automate Rust upgrades. |
| Shell | Preferrable | [Bash](https://www.gnu.org/software/bash/) | \>= 5.2.15 | 5.2.15 | Required for scripts embedded into [`justfile`](./justfile). If you don't want to use [`just`](https://just.systems/) you probably don't need this shell. |
| Command Runner | Preferrable | [`just`](https://just.systems/) | \>= 1.42.4 | 1.40.0 | All commands from [`justfile`](./justfile) could be run without [`just`](https://just.systems/), but it makes development more convenient. |
| SQlite Prompt | Preferrable | [`sqlite3`](https://sqlite.org/cli.html) | \>= 3.40.1 | 3.40.1 | Used by [`just db`](./justfile) recipe to open interactive prompt to SQlite database of the project. |
| Command Line HTTP client | Preferrable | [`curl`](https://curl.se/) | \>= 8.14.1 | 8.14.1 | Used by `just _rust-stable-version` recipe to determine current stable version of Rust. Indirectly, used by `just upgrade-rust` depends on `curl` through `_rust-stable-version` recipe. |
| Text stream editor | Preferrable | [`sed`](https://www.gnu.org/software/sed/) | \>= 4.9 | 4.9 | Similar to `curl`, Used by `just _rust-stable-version` recipe to determine current stable version of Rust. Indirectly, used by `just upgrade-rust` depends on `curl` through `_rust-stable-version` recipe. |
| TOML Query | Preferrable | [tomlq](https://crates.io/crates/tomlq) | \>= 0.2.2 | 0.2.2 | Similar to `curl`, Used by `just _rust-stable-version` recipe to determine current stable version of Rust. Indirectly, used by `just upgrade-rust` depends on `curl` through `_rust-stable-version` recipe. |
| Static Site Generator | Preferrable | [zola](https://www.getzola.org) | \>= 0.20.0 | 0.20.0 | Use `zola build` in aboutPages to build the about pages and serve from /about |
Community
---------
We're in `#hagrid` on OFTC IRC, also reachable via Matrix as `#hagrid:stratum0.org`.
# Contribution
## Housekeeping
### Rust version upgrade
Take a look at `just upgrade-rust` recipe.
It bumps used version of Rust to the current stable version
(as [declared by manifest](https://static.rust-lang.org/dist/channel-rust-stable.toml)).