home/Projects/kompose/MIGRATION_GUIDE.md

Kompose Configuration Update - Migration Guide

Overview

This update restructures your Kompose project to be more secure and maintainable by:

1. Separating sensitive data - All secrets moved to secrets.env
2. Stack-scoped variables - Configuration variables prefixed with stack names
3. Centralized configuration - All variables defined in top-level .env
4. Automatic secret generation - Generate cryptographically secure secrets with one command
5. Traefik control - Enable/disable Traefik per service with ${STACK}_TRAEFIK_ENABLED

Files Created

1. .env (Updated)

• Contains NON-SENSITIVE configuration for all stacks
• Variables are scoped with stack names (e.g., TRACK_TRAEFIK_HOST, AUTH_DB_NAME)
• Committed to git

2. secrets.env.template

• Template file for generating secrets
• Contains placeholder values: CHANGE_ME_GENERATE_WITH_KOMPOSE
• Committed to git as a reference

3. secrets.env (Generated)

• Contains ALL SENSITIVE DATA (passwords, tokens, keys)
• Auto-generated from template with ./kompose.sh --generate-secrets
• NEVER committed to git (automatically added to .gitignore)

4. kompose.sh (Updated)

• Now loads both .env and secrets.env
• New --generate-secrets command for generating random secrets
• Automatically backs up existing secrets.env before regeneration

Migration Steps

Step 1: Generate Secrets

# This will create secrets.env from the template
./kompose.sh --generate-secrets

This command will:

• Read secrets.env.template
• Generate cryptographically secure random values for all secrets
• Save them to secrets.env
• Add secrets.env to .gitignore if not already present
• Backup existing secrets.env if it exists

Step 2: Update Your Stack Files

Each stack needs to be updated to use the new variable naming pattern:

Before (track/.env):

COMPOSE_PROJECT_NAME=track
DOCKER_IMAGE=ghcr.io/umami-software/umami:postgresql-latest
DB_NAME=umami
TRAEFIK_HOST=umami.pivoine.art
APP_PORT=3000
APP_SECRET=changeme

After (track/.env):

COMPOSE_PROJECT_NAME=track
# All other variables are now in root .env and secrets.env

Before (track/compose.yaml):

environment:
  DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}
  APP_SECRET: ${APP_SECRET}
labels:
  - 'traefik.enable=true'
  - 'traefik.http.routers.${COMPOSE_PROJECT_NAME}-web.rule=Host(`$TRAEFIK_HOST`)'

After (track/compose.yaml):

environment:
  DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${TRACK_DB_NAME}
  APP_SECRET: ${TRACK_APP_SECRET}
labels:
  - 'traefik.enable=${TRACK_TRAEFIK_ENABLED}'
  - 'traefik.http.routers.${COMPOSE_PROJECT_NAME}-web.rule=Host(`${TRACK_TRAEFIK_HOST}`)'

Step 3: Update Root .env

Add configuration for each stack in the root .env:

# -------------------------------------------------------------------
# TRACK Stack (Umami Analytics)
# -------------------------------------------------------------------
TRACK_TRAEFIK_ENABLED=true
TRACK_TRAEFIK_HOST=umami.pivoine.art
TRACK_DB_NAME=umami
TRACK_DOCKER_IMAGE=ghcr.io/umami-software/umami:postgresql-latest
TRACK_APP_PORT=3000

Step 4: Update secrets.env.template

Add secret placeholders for each stack:

# -------------------------------------------------------------------
# TRACK Stack Secrets (Umami)
# -------------------------------------------------------------------
TRACK_APP_SECRET=CHANGE_ME_GENERATE_WITH_KOMPOSE

Step 5: Regenerate Secrets (if needed)

After updating the template, regenerate secrets:

./kompose.sh --generate-secrets

Your old secrets will be backed up automatically.

Variable Naming Convention

Stack Configuration Variables (in root .env)

{STACK_NAME}_{VARIABLE_NAME}

Examples:
TRACK_TRAEFIK_HOST=umami.pivoine.art
TRACK_DB_NAME=umami
TRACK_DOCKER_IMAGE=ghcr.io/umami-software/umami:postgresql-latest
AUTH_TRAEFIK_HOST=auth.pivoine.art
AUTH_DB_NAME=keycloak

Stack Secrets (in secrets.env)

{STACK_NAME}_{SECRET_NAME}

Examples:
TRACK_APP_SECRET=<generated-64-char-hex>
AUTH_KC_ADMIN_PASSWORD=<generated-32-char-password>
DB_PASSWORD=<generated-32-char-password>

Shared Variables (in root .env)

DB_USER=valknar
DB_HOST=postgres
DB_PORT=5432
ADMIN_EMAIL=admin@example.com
NETWORK_NAME=kompose

Example Stack Configurations

Example 1: Track Stack (Umami)

Root .env:

TRACK_TRAEFIK_ENABLED=true
TRACK_TRAEFIK_HOST=umami.pivoine.art
TRACK_DB_NAME=umami
TRACK_DOCKER_IMAGE=ghcr.io/umami-software/umami:postgresql-latest

secrets.env.template:

TRACK_APP_SECRET=CHANGE_ME_GENERATE_WITH_KOMPOSE

track/compose.yaml:

services:
  umami:
    image: ${TRACK_DOCKER_IMAGE}
    environment:
      DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${TRACK_DB_NAME}
      APP_SECRET: ${TRACK_APP_SECRET}
    labels:
      - 'traefik.enable=${TRACK_TRAEFIK_ENABLED}'
      - 'traefik.http.routers.${COMPOSE_PROJECT_NAME}-web.rule=Host(`${TRACK_TRAEFIK_HOST}`)'

Example 2: Auth Stack (Keycloak)

Root .env:

AUTH_TRAEFIK_ENABLED=true
AUTH_TRAEFIK_HOST=auth.pivoine.art
AUTH_DB_NAME=keycloak
AUTH_DOCKER_IMAGE=quay.io/keycloak/keycloak:latest

secrets.env.template:

AUTH_KC_ADMIN_PASSWORD=CHANGE_ME_GENERATE_WITH_KOMPOSE

auth/compose.yaml:

services:
  keycloak:
    image: ${AUTH_DOCKER_IMAGE}
    environment:
      KC_DB_URL: jdbc:postgresql://${DB_HOST}:${DB_PORT}/${AUTH_DB_NAME}
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${AUTH_KC_ADMIN_PASSWORD}
    labels:
      - 'traefik.enable=${AUTH_TRAEFIK_ENABLED}'
      - 'traefik.http.routers.${COMPOSE_PROJECT_NAME}-web.rule=Host(`${AUTH_TRAEFIK_HOST}`)'

Traefik Control

Every service now has a ${STACK}_TRAEFIK_ENABLED variable that controls whether Traefik routes to it:

labels:
  - 'traefik.enable=${TRACK_TRAEFIK_ENABLED}'  # true or false

To disable Traefik for a stack, simply set it to false in the root .env:

TRACK_TRAEFIK_ENABLED=false

Secret Generation Patterns

The --generate-secrets command generates different types of secrets based on variable naming:

Variable Pattern	Generated Secret Type	Length	Example
*_PASSWORD	Alphanumeric password	32 chars	DB_PASSWORD, ADMIN_PASSWORD
*_SECRET, *_ENCRYPTION_KEY	Hex string	64 chars (32 bytes)	TRACK_APP_SECRET, N8N_ENCRYPTION_KEY
*_TOKEN	Alphanumeric token	40 chars	GITEA_RUNNER_TOKEN
*_HASH	Hex hash	64 chars (32 bytes)	PASSWORD_HASH
Default	Alphanumeric	32 chars	Any other variable

Security Best Practices

✅ DO:

• Keep secrets.env in .gitignore
• Use the provided secrets.env.template as reference
• Regenerate secrets when setting up new environments
• Use stack-scoped variable names
• Store secrets in secrets.env only

❌ DON'T:

• Commit secrets.env to git
• Hard-code secrets in compose files
• Share secrets in plain text (use password managers)
• Use the same secrets across environments
• Store configuration in stack .env files anymore

Quick Reference

Generate secrets:

./kompose.sh --generate-secrets

Start all stacks:

./kompose.sh "*" up -d

View help:

./kompose.sh --help

List stacks:

./kompose.sh --list

Troubleshooting

"Secrets file not found"

Run: ./kompose.sh --generate-secrets

"Variable not set" errors

Make sure you've:

1. Updated root .env with stack-scoped variables
2. Generated secrets.env
3. Updated compose files to use new variable names

Need to regenerate a single secret?

Edit secrets.env directly and replace the value, or regenerate all secrets (old secrets will be backed up).

Example Complete Setup

See the .new files in track/ and auth/ directories for complete examples of the new structure.

To apply them:

cd track
mv compose.yaml.new compose.yaml
mv .env.new .env

cd ../auth
mv compose.yaml.new compose.yaml
mv .env.new .env

Then regenerate your secrets:

./kompose.sh --generate-secrets