git.stella-ops.org/docs/operations/configuration-migration.md

Configuration Migration Guide

This guide covers migrating from the legacy multi-directory configuration structure to the consolidated etc/ structure.

Legacy vs New Structure

Files to Move

Legacy Location	New Location	Action
certificates/*.pem	etc/certificates/trust-roots/	Move
certificates/*-signing-*.pem	etc/certificates/signing/	Move
config/env/.env.*.example	etc/crypto/profiles/*/env.sample	Move + rename
config/crypto-profiles.sample.json	Delete (superseded by etc/crypto/)	Delete
policies/	etc/policy/	Move
etc/rootpack/*	etc/crypto/profiles/*	Rename

Directories to Remove After Migration

certificates/          # Moved to etc/certificates/
config/                # Moved to etc/crypto/ and etc/env/
policies/              # Moved to etc/policy/

Directories That Stay

plugins/               # Runtime artifacts, not configuration
opt/                   # Vendor packages
offline/               # Air-gap operational data

Migration Steps

Step 1: Backup Current Configuration

# Create backup
tar -czvf config-backup-$(date +%Y%m%d).tar.gz \
    certificates/ \
    config/ \
    policies/ \
    etc/

Step 2: Run Migration Script

./devops/scripts/migrate-config.sh

This script:

1. Creates the new directory structure
2. Moves files to new locations
3. Updates path references
4. Validates the migration

Step 3: Manual Migration (if script not available)

# Create new directories
mkdir -p etc/certificates/trust-roots
mkdir -p etc/certificates/signing
mkdir -p etc/crypto/profiles/{cn,eu,kr,ru,us-fips}
mkdir -p etc/env
mkdir -p etc/policy/packs
mkdir -p etc/policy/schemas

# Move certificates
mv certificates/*-bundle*.pem etc/certificates/trust-roots/
mv certificates/*-root*.pem etc/certificates/trust-roots/
mv certificates/*-signing-*.pem etc/certificates/signing/

# Move crypto profiles
mv etc/rootpack/cn/* etc/crypto/profiles/cn/
mv etc/rootpack/eu/* etc/crypto/profiles/eu/
mv etc/rootpack/kr/* etc/crypto/profiles/kr/
mv etc/rootpack/ru/* etc/crypto/profiles/ru/
mv etc/rootpack/us-fips/* etc/crypto/profiles/us-fips/

# Move environment profiles
mv config/env/.env.fips.example etc/crypto/profiles/us-fips/env.sample
mv config/env/.env.eidas.example etc/crypto/profiles/eu/env.sample
mv config/env/.env.ru-free.example etc/crypto/profiles/ru/env.sample
mv config/env/.env.sm.example etc/crypto/profiles/cn/env.sample
mv config/env/.env.kcmvp.example etc/crypto/profiles/kr/env.sample

# Move policies
mv policies/starter-day1.yaml etc/policy/packs/
mv policies/schemas/* etc/policy/schemas/

# Remove legacy directories
rmdir etc/rootpack/cn etc/rootpack/eu etc/rootpack/kr etc/rootpack/ru etc/rootpack/us-fips etc/rootpack
rmdir config/env config
rmdir certificates
rmdir policies/schemas policies

Step 4: Update Docker Compose Files

Update volume mounts in devops/compose/docker-compose.*.yaml:

Before:

volumes:
  - ../../certificates:/etc/ssl/certs/stellaops:ro
  - ../../config/crypto-profiles.json:/app/config/crypto-profiles.json:ro

After:

volumes:
  - ../../etc/certificates/trust-roots:/etc/ssl/certs/stellaops:ro
  - ../../etc/crypto:/app/etc/crypto:ro

Step 5: Update Environment References

Before:

source config/env/.env.fips.example

After:

cp etc/crypto/profiles/us-fips/env.sample etc/crypto/profiles/us-fips/env
source etc/crypto/profiles/us-fips/env

Step 6: Validate Migration

# Validate configuration structure
./devops/scripts/validate-config.sh

# Test service startup
docker compose up -d --dry-run

Docker Compose Reference Updates

Scanner Service

scanner:
  volumes:
    # Configuration
    - ../../etc/scanner:/app/etc/scanner:ro
    - ../../etc/certificates/trust-roots:/etc/ssl/certs/stellaops:ro
    - ../../etc/crypto:/app/etc/crypto:ro

    # Plugin binaries (stays at root)
    - ../../plugins/scanner:/app/plugins/scanner:ro

Authority Service

authority:
  volumes:
    - ../../etc/authority:/app/etc/authority:ro
    - ../../etc/certificates/signing:/app/etc/signing:ro

Policy Gateway

policy-gateway:
  volumes:
    - ../../etc/policy:/app/etc/policy:ro

Environment Variable Changes

Crypto Profile Selection

Before:

CRYPTO_PROFILE_PATH=/app/config/crypto-profiles.json
CRYPTO_REGION=fips

After:

STELLAOPS_CRYPTO_PROFILE=us-fips
# Profile loaded from: /app/etc/crypto/profiles/us-fips/crypto.profile.yaml

Certificate Paths

Before:

SSL_CERT_DIR=/etc/ssl/certs
STELLAOPS_TRUST_ROOTS=/app/certificates

After:

STELLAOPS_CERTIFICATES__TRUSTROOTSDIR=/app/etc/certificates/trust-roots
STELLAOPS_CERTIFICATES__SIGNINGDIR=/app/etc/certificates/signing

Rollback Procedure

If issues occur:

# Restore from backup
tar -xzvf config-backup-*.tar.gz

# Revert Docker Compose changes
git checkout devops/compose/

# Restart services
docker compose down && docker compose up -d

Post-Migration Checklist

• All services start without configuration errors
• Certificate validation passes
• Crypto operations use correct profile
• Policy gates evaluate correctly
• Scanner plugins load successfully
• Notifications send via configured providers
• Remove legacy directories once validated

Related Documentation

• Configuration Guide
• Air-Gap Deployment
• Docker Compose README