Verified Commit 3442216e authored by Katharina Fey's avatar Katharina Fey 🏴
Browse files

Updating documentation

parent 88333673
......@@ -4,45 +4,97 @@ A small toolkit for managing and rebuilding [NixOS] servers.
It provides a simple HTTP server which listens for certain token-hashes
which are sent out by our git backend (gitlab in my case).
If the hash matches, a request is handled.
The actual token is used as a secret for a rebuild key.
It listens for update events via a small HTTP server
and uses the configuration in your repository to deploy the server.
This way an attacker would need to know the actual token
to get access to the rebuild-key,
but the hash can be stored as part of the configuration
for request checking, without revealing the token secret
## Configuration
## Setup
There's two ways to use `forge`
`forge` has two levels of configuration.
One is required to make the daemon run and react to update events,
the second is repository specific configuration and deploy secrets.
* As part of the `forge.nix` module (recommended)
* As a standalone server
When running `forge` manually you need to provide a trusted token
either via environment variable (`FORGE_TOKEN`) or a CLI argument.
The server has the ability to either read it's configuration from
`forge.yml` which can be provided as a path via a CLI flag
or the `FORGE_CONFIG_PATH` env variable.
Alternatively you can configure `forge` via the [`nixos`] module.
Note that you will have to manually do SSL termination
via an external http proxy.
In case it is run via the `forge.nix` module (oh yea!)
you can configure the server with the following code:
services.forge = {
enable = true; # Enable `forge`
route = "/rebuild"; # The route to handle (on port 443)
enable = true;
port = 9090;
token = "<validation token here>";
There are many more options exposed via the `forge.nix` module so do check those out
if you want to have more fine-grained control over your server.
Inside a repository `forge` depends on `forge.yml` as a configuration
that provides deploy commands and secrets.
## Security Layout
+===========+ +===============+ +=================+
| Token | - blake2 - | Encryption | | Verification |
+===========+ | Key | - blake2 - | Token |
+===============+ +=================+
* `Token` is the secret handled by your git server
* `Key` is the hashed token and used for encryption
* `Verification Token` is a hash of the `Key` which is used
for request verification
The verification token can be kept in your global system configuration
because from it no other secrets can be derived. Other deploy secrets
can be kept in your configuration repository because they can be
encrypted with the key, derived from the secret token.
## Setup
## Environment Variables
`forgectl` provides some utilities to configure itself.
To generate a token you should use a tool such as `pwgen`.
Keep this token secret!
It's possible to configure `forge` via it's environment.
This might be useful when running `forgectl` via `execline` or in an automated setup.
$ export FORGE_TOKEN=$(pwgen 64)
Now generate a verification token from the secret token.
You can embed this into your forge configuration.
echo $FORGE_TOKEN | forgectl setup
At this point you can also setup deploy secrets. This could be used
for ssh keys to deploy locally.
$ ssh-keygen -t ed25519 -f tmp_key -N ''
Generating public/private ed25519 key pair.
The key's randomart image is:
+--[ED25519 256]--+
| ..+OB |
| o..oBo*o |
| o. + *++o |
| .. +.B o+|
| .S.o = +o.|
| o. + . |
| +.o . E.|
| +.= . +|
| ..o.o .o|
$ cat tmp_key | target/debug/forgectl encrypt -s (echo $FORGE_TOKEN)
iv: FxA7XaLY3mdRhUhdZNd5AdC1Qz+b7hUDEpysOldFcbR/z+XIfAoZ7EEQvgQpwYpNXogiBqVkbZvepAHk44l/LA==
nonce: nFOE8IDXMWJ2mbgNMC+0J3HEdnbrusGaNL266c7sieJpqZWlRiiXzEouL7Pza1v3Ep8ibGnwzwAUOmOuRhjf2g==
data: iyT3gdW4AOiwgxxHkoZyPZg6BHoF2RxH/cVcGDey1Es8PeCmMmRaD9s8uawXc264WYbrFmLYYomyHPHwzSGnZz9UUCxH1Xi/BxMCckVFFNSa0THNrYVUfHfuwyCIXP7SAnJ1SGRMvb/ZXOQ3xXnPmiBLwuP1CRGcBMDqTwdtqomOMMGRmrgvHw+9xOEv3m1kHI0DMiQCRpYb+kNMZo93hfbU0lARf760PZ2Y4MYjCy0mjdyaTntc4pw6BMUG5kCYpIDek/XJCPqc2bn3yv2Y9JmGFAn7yb1MRUruY60+wDLER7OyXnaDJ9EX7QeaGM87O05m9l+Jxif67BLsC8IAKBKQwg7krq+DEiXJ/yOhj9d0z+bkjbWtxIetdlSlHAGQSUyeZT7FbZu2pKLZBUhkwbxKNiEh4JfAKmX0vgutOc0tz0If+cOwkGGDiye+COv+j8/a15M6F9gAxtkH+KkgfYPfcp7boKzgv/fK/cSNhDZkB9faoLLyctRUAA2qbDk+86H4uqFxJg3mgL2Sjbq8NB3nl7ZfKaQ0pUguQgt1RHczumz2fJeJGaa/MA==
- `FORGE_DATA` the data that should be encrypted
- `FORGE_SECRET` the token that is used as the encryption key base
Add the generated YAML to the `secrets` section of the `forge.yml` configuration.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment