Skip to main content

Docker Integration

Arcan integrates with Docker Compose and Docker Swarm to inject secrets into containerized workloads.

Docker Compose​

Generate .env files from Arcan secrets for use with docker compose up.

Basic workflow​

# Store secrets in Arcan
arcan kv set DATABASE_URL "postgres://user:pass@db:5432/app" -r myapp -e prod
arcan kv set REDIS_URL "redis://cache:6379" -r myapp -e prod

# Generate .env file
arcan docker compose -r myapp -e prod

# Start containers
docker compose up -d

Using with docker-compose.yaml​

Reference the generated .env file in your compose configuration:

# docker-compose.yaml
services:
  api:
    image: myapp:latest
    env_file:
      - .env
    ports:
      - "8080:8080"

  worker:
    image: myapp:latest
    env_file:
      - .env
    command: ["worker"]

Per-environment files​

arcan docker compose -r myapp -e dev -o .env.dev
arcan docker compose -r myapp -e staging -o .env.staging
arcan docker compose -r myapp -e prod -o .env.prod

JSON format​

arcan docker compose -r myapp -e prod --format=json

Piping to other tools​

arcan docker compose -r myapp -e prod --stdout | grep DATABASE

Docker Swarm​

Sync Arcan secrets to Docker Swarm's built-in secrets store. Swarm secrets are encrypted at rest and only available to services that explicitly reference them.

Sync workflow​

# Sync secrets from Arcan to Swarm
arcan docker swarm sync -r myapp -e prod

# Preview what would be synced
arcan docker swarm sync -r myapp -e prod --dry-run

# List managed secrets
arcan docker swarm ls

# Clean up
arcan docker swarm rm -r myapp -e prod
arcan docker swarm rm --all

Using Swarm secrets in services​

After syncing, reference the secrets in your docker-compose.yaml (deploy mode):

# docker-compose.yaml (Swarm stack)
services:
  api:
    image: myapp:latest
    secrets:
      - arcan_prod_DATABASE_URL
      - arcan_prod_API_KEY
    environment:
      DATABASE_URL_FILE: /run/secrets/arcan_prod_DATABASE_URL

secrets:
  arcan_prod_DATABASE_URL:
    external: true
  arcan_prod_API_KEY:
    external: true

Swarm mounts secrets as files at /run/secrets/<name>. Your application reads them from disk.

Custom prefix​

By default, secrets are named arcan_<env>_<KEY>. Override with --prefix:

arcan docker swarm sync -r myapp -e prod --prefix="myapp_"
# Creates: myapp_DATABASE_URL, myapp_API_KEY, etc.

arcan docker swarm sync -r myapp -e prod --prefix=""
# Creates: DATABASE_URL, API_KEY (no prefix)

Security Notes​

  • .env files are written with 0600 permissions (owner read/write only)
  • Add .env* to your .gitignore to prevent accidental commits
  • Values containing spaces, quotes, or shell metacharacters are automatically quoted
  • Swarm secrets are labeled with managed-by=arcan, arcan-realm, and arcan-env for tracking
  • Swarm secrets are immutable; updates remove and recreate the secret