Docker Integration

This guide covers using KeyEnv with Docker and docker-compose.

Development with docker-compose

Option 1: Pull secrets before starting

# Pull secrets to .env
keyenv pull

# Start containers (docker-compose reads .env automatically)
docker-compose up

Your docker-compose.yml:

version: '3.8'

services:
  app:
    build: .
    env_file:
      - .env
    ports:
      - "3000:3000"

Option 2: Use keyenv run

# Start with secrets injected
keyenv run -- docker-compose up

This injects secrets into the docker-compose process, which passes them to containers.

Production Deployments

Build-time vs Runtime Secrets

Never include secrets in Docker images. Always inject at runtime.

Wrong - Secrets baked into image:

# DON'T DO THIS
COPY .env /app/.env

Correct - Secrets injected at runtime:

# docker-compose.prod.yml
services:
  app:
    image: myapp:latest
    env_file:
      - .env.production

CI/CD Workflow

# .github/workflows/deploy.yml
- name: Pull production secrets
  env:
    KEYENV_TOKEN: ${{ secrets.KEYENV_TOKEN }}
  run: keyenv pull -e production -o .env.production

- name: Deploy
  run: docker-compose -f docker-compose.prod.yml up -d

Docker Swarm / Kubernetes

For orchestrators, use Docker secrets or Kubernetes secrets:

Docker Swarm

# Pull secret and create Docker secret
keyenv get DATABASE_URL -e production -q | docker secret create db_url -

Kubernetes

For Kubernetes, we recommend using the External Secrets Operator (ESO) integration for automatic secret synchronization:

See the Kubernetes Integration Guide for complete ESO setup instructions.

For simple one-time syncs, you can use the CLI:

# Pull secrets and create K8s secret
keyenv pull -e production -o- | kubectl create secret generic app-secrets --from-env-file=/dev/stdin

Multi-environment Setup

# Development
keyenv pull -e development -o .env.development

# Staging
keyenv pull -e staging -o .env.staging

# Production
keyenv pull -e production -o .env.production

# docker-compose.yml
services:
  app:
    build: .
    env_file:
      - .env.${ENVIRONMENT:-development}

ENVIRONMENT=staging docker-compose up

Best Practices

Never commit .env files - Add them to .gitignore
Use .env.example - Commit a template without values
Pull fresh secrets - Don't cache secrets in CI/CD
Use different credentials - Each environment should have unique secrets

Docker Integration

On this page