cplieger/docker-age repository overview

⁠docker-age

docker-age decrypts the age⁠-encrypted .env files in a git checkout on your server, right before your Docker Compose stacks start. Your secrets stay encrypted in git. It does not encrypt files or start your stacks.

⁠What it does

docker-age lets you commit every secret encrypted and still start each stack with a plain .env file:

• Writes apps/x/.env next to each apps/x/.env.enc and never changes the encrypted file, so git pull stays clean.
• Fails when a file will not decrypt or encrypted text sits at a plain file's name, so your deploy can stop.
• Tries every key in your identity file, so you rotate a key by adding the new one beside the old.
• Also decrypts any other file named <name>.enc, or one file you pipe through it.

⁠Who it is for

docker-age is built for Docker Compose stacks deployed from a git checkout, with each secret committed as an age-encrypted file. You need the age command-line tool to encrypt your files and an identity file from age-keygen on each server. Your deploy step must run docker exec before your stacks start.

Two other projects suit a different setup:

• Consider SOPS⁠ if you want an editor for encrypted YAML, JSON, ENV and INI files. It can use keys from AWS KMS, GCP KMS, Azure Key Vault, age or PGP.
• Consider git-crypt⁠ if you want files decrypted whenever the repository is checked out, with keys shared through GPG.

docker-age is free software under the Apache-2.0 license.

⁠Pull

docker pull cplieger/docker-age:latest

Also published to ghcr.io/cplieger/docker-age with identical images and tags. Release versions are tagged vX.Y.Z alongside latest.

⁠Quick start

# Example compose for docker-age. See docs/configuration.md and docs/hardening.md for all configuration options and hardening.
services:
  age:
    image: ghcr.io/cplieger/docker-age:latest
    container_name: age
    # Before each "docker compose up", your deploy step runs
    # "docker exec age /age-decrypt decrypt --ext .env" to write the .env files.
    restart: unless-stopped  # stays up between deploys so the deploy step can reach it

    environment:
      IDENTITY_PATH: "/age/keys.txt"  # required, your age identity file

    volumes:
      # Put your age identity in keys.txt, then run "sudo chown 65532:65532 keys.txt"
      # and "sudo chmod 600 keys.txt" before the first decrypt.
      - "/path/to/age-keys:/age:ro"
      # Your checkout with the .env.enc files. For each folder that holds one, run
      # "sudo chgrp 65532 <folder>" and "sudo chmod g+w <folder>" before the first decrypt.
      - "/path/to/repo:/repo"

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Configuration⁠
• Security⁠
• How docker-age works⁠
• Contributing⁠
• Releases and changelog⁠

⁠License

Apache-2.0. See LICENSE⁠.

The image carries the license text of every bundled component under /usr/share/licenses/, including the BSD-3-Clause text of the age⁠ library it links.