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

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

### Step 2: Run Migration Script

```bash
./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)

```bash
# 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:**
```yaml
volumes:
  - ../../certificates:/etc/ssl/certs/stellaops:ro
  - ../../config/crypto-profiles.json:/app/config/crypto-profiles.json:ro
```

**After:**
```yaml
volumes:
  - ../../etc/certificates/trust-roots:/etc/ssl/certs/stellaops:ro
  - ../../etc/crypto:/app/etc/crypto:ro
```

### Step 5: Update Environment References

**Before:**
```bash
source config/env/.env.fips.example
```

**After:**
```bash
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

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

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

## Docker Compose Reference Updates

### Scanner Service

```yaml
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

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

### Policy Gateway

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

## Environment Variable Changes

### Crypto Profile Selection

**Before:**
```bash
CRYPTO_PROFILE_PATH=/app/config/crypto-profiles.json
CRYPTO_REGION=fips
```

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

### Certificate Paths

**Before:**
```bash
SSL_CERT_DIR=/etc/ssl/certs
STELLAOPS_TRUST_ROOTS=/app/certificates
```

**After:**
```bash
STELLAOPS_CERTIFICATES__TRUSTROOTSDIR=/app/etc/certificates/trust-roots
STELLAOPS_CERTIFICATES__SIGNINGDIR=/app/etc/certificates/signing
```

## Rollback Procedure

If issues occur:

```bash
# 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](./configuration-guide.md)
- [Air-Gap Deployment](../24_OFFLINE_KIT.md)
- [Docker Compose README](../../devops/compose/README.md)