Quickstart

nox uses a pull-strategy to synchronize secrets from Git repositories down to the host machines. We therefore set up a git repository that contains all encrypted secrets and a config for the host-system.

Set up the repository

Start with an empty git repository to get started. Either local with git init or clone an existing repository.

mkdir -p keys testapp
touch .gitignore

Don’t forget to adjust your .gitignore to not accidentally commit your keys.

keys/
.nox-state.json
.nox.yaml

# Ignore all .env files
.env
**/.env
*.env
**/*.env

Create a key

To get started you need to have an age private key first. See the age documentation for more information. nox can be used for a simplified way to create a private key.

age-keygen -o keys/key.txt

(Alternatively) using nox

nox generate key -o keys/key.txt

Create and encrypt a secret

# Example secret file
echo "DATABASE_URL=postgresql://user:pass@localhost/db" > testapp/database.env

# Encrypt using your recipient
age -i keys/key.txt -r age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -o testapp/database.env.age testapp/database.env

Remember to replace the recipient with your own.

It is technically possible to encrypt files with nox, but this is not recommended. Just for documentation, the equivalent would look like so:

nox encrypt -r age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -i testapp/database.env -o testapp/database.env.age --identity keys/key.txt

Now push the repository to your Git provider. Make sure to not publish eny unencrypted secrets…the .gitignore file should help with that.

Create or generate configuration

We now need to set up nox on the host system we want to consume the secrets on.

You can either generate the config from a template or generate one with nox generate config. The bare command will generate a minimal config file called .nox.yaml

interval: 10m
age:
    identity: ""
statePath: .nox-state.json
git:
    repo: ""
    branch: main
apps: {}

You can add flags to the command to customize the config on generation or to extend it with new apps. Let’s populate our existing config for now:

interval: "10m"            # how often to sync
age:
  identity: "keys/key.txt" # private key for decryption
  recipients:              # optional, for encryption use-cases
    - "age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
statePath: ".nox-state.json"

# global Git defaults
git:
  repo: "git@github.com:your-org/secrets-repo.git"
  branch: "main"

apps:
  production:
    # Inherits git defaults
    files:
      - path: "testapp/database.env.age"
        output: "/opt/testapp/.env"

Start nox

After configuring all secrets that need to be synced with the desired locations, we can now start the first sync. Let’s test it first with a dry-run (secrets will be printed to the console):

nox sync --dry-run

If everything is fine, we can now run the sync without the dry-run flag:

nox sync