Redflag/docs/4_LOG/December_2025/DOCKER_SECRETS_SETUP-2025-12-17.md

Docker Secrets Setup Guide - RedFlag v0.2.x

Overview

Docker secrets provide secure, encrypted storage for sensitive configuration values. This guide explains how to use Docker secrets instead of .env files for production deployments.

Secrets vs Environment Variables

When to use Docker Secrets:

• Production deployments
• Shared Docker Swarm environments
• When security compliance requires encrypted secrets at rest

When to use .env files:

• Local development
• Testing environments
• Single-node Docker Compose setups without security requirements

Prerequisites

• Docker Engine 1.13 or later (for Docker secrets)
• Docker Compose
• RedFlag v0.2.x or later

Setup Process

Step 1: Start RedFlag (Initial Setup Mode)

docker compose up -d

The server will start in welcome mode. Navigate to your RedFlag server's setup page (typically at http://your-server:8080/setup) to configure.

Step 2: Complete Setup

Complete the configuration form in the setup UI. The system will:

• Create cryptographically secure passwords and secrets
• Generate JWT signing secret
• Generate Ed25519 signing keys
• Display Docker secret commands and configuration instructions

The setup UI will provide exact commands and configuration changes needed.

Step 3: Create Docker Secrets

The setup UI will provide the exact commands. Run them on your Docker host:

# Example commands (use the values from your setup UI):
printf '%s' 'your-admin-password' | docker secret create redflag_admin_password -
printf '%s' 'your-jwt-secret' | docker secret create redflag_jwt_secret -
printf '%s' 'your-db-password' | docker secret create redflag_db_password -
printf '%s' 'your-signing-key' | docker secret create redflag_signing_private_key -

Note: Always use printf instead of echo to preserve special characters properly.

Step 4: Apply Configuration

The setup UI will provide configuration changes including:

• Volume mounts for Docker secrets
• Any docker-compose.yml modifications needed

Follow the instructions provided by the setup UI to update your configuration.

Step 5: Restart With Secrets

docker compose down
docker compose up -d

Available Secrets

redflag_admin_password

• Purpose: Web UI admin authentication
• Format: Plain text password
• Security: Should be at least 16 characters, mixed case, numbers, symbols
• Rotation: Use UI to change, then recreate secret

redflag_jwt_secret

• Purpose: Signing JWT authentication tokens
• Format: Base64-encoded 32+ bytes
• Rotation: Recreate secret, all users must re-login
• Impact: All active sessions invalidated

redflag_db_password

• Purpose: PostgreSQL authentication
• Format: Plain text password
• Rotation: Update in PostgreSQL, then recreate secret
• Impact: Brief database connection interruption

redflag_signing_private_key

• Purpose: Ed25519 key for signing agent updates
• Format: Hex-encoded 64-character private key
• Rotation: Complex - requires re-signing all packages
• Impact: Agents need updated public key

Troubleshooting

Issue: "secret not found" error

Cause: Secret doesn't exist in Docker

Solution: Create the secret:

echo 'your-value' | docker secret create redflag_admin_password -

Issue: "external secret not found" on compose up

Cause: Secrets defined in compose but not created

Solution: Create all four secrets before running docker compose up

Issue: Secrets not loading

Check:

# Verify secrets exist
docker secret ls

# Check server logs
docker compose logs server

# Verify config
docker exec redflag-server cat /run/secrets/redflag_admin_password

Migrating from .env to Secrets

1. Extract values from .env:

grep -E "ADMIN_PASSWORD|JWT_SECRET|DB_PASSWORD|SIGNING_PRIVATE" config/.env

2. Create secrets:

source config/.env
echo "$REDFLAG_ADMIN_PASSWORD" | docker secret create redflag_admin_password -
echo "$REDFLAG_JWT_SECRET" | docker secret create redflag_jwt_secret -
echo "$REDFLAG_DB_PASSWORD" | docker secret create redflag_db_password -
echo "$REDFLAG_SIGNING_PRIVATE_KEY" | docker secret create redflag_signing_private_key -

3. Remove sensitive values from .env (keep non-sensitive config only)

4. Restart:

docker compose down
docker compose up -d

Security Best Practices

1. Never commit secrets - Ensure .env files with real secrets are gitignored
2. Use strong passwords - Minimum 16 characters for admin password
3. Rotate regularly - Change secrets every 90 days in production
4. Limit access - Only mount secrets on server container (not agents)
5. Audit access - Monitor secret access logs in Docker daemon
6. Backup secrets - Keep encrypted backup of secret values
7. Use unique secrets - Don't reuse secrets across environments

Development Mode

To use .env files for development (no Docker secrets needed):

Note: The config/.env file is now completely optional. The server will automatically create it if needed.

1. Create config/.env with:

REDFLAG_ADMIN_PASSWORD=dev-password
REDFLAG_JWT_SECRET=dev-jwt-secret-key-min-32-bytes
REDFLAG_DB_PASSWORD=dev-db-password
REDFLAG_SIGNING_PRIVATE_KEY=generated-key-from-setup

2. Start normally:

docker compose up -d

Config loader will automatically use .env when Docker secrets are not available.

Simplified option: You can skip creating the .env file entirely for Docker secrets mode. The container will handle it automatically.

Reference

• Docker Secrets Documentation
• Docker Compose Secrets
• RedFlag Security Documentation: docs/SECURITY.md