Skip to content

Docker Secrets

Guide to using Docker secrets for secure configuration management in Bifolk.

Target Audience: System administrators, DevOps engineers

Overview

Docker secrets provide a secure way to manage sensitive configuration values. Instead of storing passwords and keys in environment variables (which are visible in process listings), secrets are stored in files that are mounted into the container at runtime.

Secret Files

Bifolk uses the following secret files:

File Purpose Required
secrets/secret_key.txt Django SECRET_KEY for cryptographic signing Yes (production)
secrets/db_password.txt PostgreSQL database password Only with PostgreSQL
secrets/email_password.txt SMTP email password Only with email
secrets/oidc_client_secret.txt OIDC client secret Only with SSO

The secrets/ directory lives next to the docker-compose.yml of each deployment setup (e.g. docker/compose-postgres/secrets/).

Setting Up Secrets

1. Create Secret Files

# Generate a strong secret key
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())" > secrets/secret_key.txt

# Set database password
echo "your-secure-db-password" > secrets/db_password.txt

# Set email password
echo "your-smtp-password" > secrets/email_password.txt

# Set OIDC secret (if using SSO)
echo "your-oidc-client-secret" > secrets/oidc_client_secret.txt

2. Set Permissions

bash scripts/bifolk_set_permissions.sh

This sets restrictive file permissions (read-only, owner-only) on the secret files.

3. Configure Docker Compose

In docker-compose.yml, secrets are declared, mounted, and pointed to via _FILE environment variables:

secrets:
  bifolk_secret_key:
    file: ../../secrets/secret_key.txt
  bifolk_email_password:
    file: ../../secrets/email_password.txt
  bifolk_oidc_client_secret:
    file: ../../secrets/oidc_client_secret.txt

services:
  bifolk-app:
    secrets:
      - bifolk_secret_key
      - bifolk_email_password
      - bifolk_oidc_client_secret
    environment:
      - DJANGO_SECRET_KEY_FILE=/run/secrets/bifolk_secret_key
      - EMAIL_PASSWORD_FILE=/run/secrets/bifolk_email_password
      - OIDC_CLIENT_SECRET_FILE=/run/secrets/bifolk_oidc_client_secret

The production compose files do not set plain environment variables for secret values. Secrets are loaded exclusively through the _FILE variables above.

How Secrets Are Read

The configuration generator (generate_config.py) reads sensitive values in this order:

  1. *_FILE environment variable pointing to a secret file
  2. Docker secret at /run/secrets/*
  3. Default value

Example: For the Django SECRET_KEY, the system checks:

  1. DJANGO_SECRET_KEY_FILE → reads the file at that path
  2. /run/secrets/bifolk_secret_key → reads Docker secret directly
  3. Auto-generates a random key (development only)

Security Best Practices

  • Never commit secret files to version control (they are in .gitignore)
  • Use strong, randomly generated values
  • Rotate secrets periodically
  • Restrict file permissions on secret files
  • Use Docker secrets instead of environment variables in production
  • Do not log secret values

Generating Secure Values

# Django SECRET_KEY
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

# Strong random password
openssl rand -base64 32