Managing credentials

How OrcheStack stores service credentials, how to rotate them safely, and what breaks if you edit them carelessly.

Where credentials are stored

Every service credential (database passwords, API keys, admin emails) lives in ./config/.env on the host. This file is chmod 600-protected and should be added to your .gitignore immediately.

The generated docker-compose.yml references credentials as ${VAR_NAME} — at container start, Docker Compose substitutes values from .env.

Rotating a credential

From the OrcheStack admin dashboard:

1. Click the service tile.
2. Click Edit config.
3. Update the field. OrcheStack runs a live connection test before letting you save.
4. Click Save & apply.

Container recreation

Docker Compose semantics: restart reuses the existing container (stale env vars); up with changed .env values detects a config hash diff and recreates. OrcheStack issues docker compose up -d --force-recreate <service> on save, which picks up the new values.

Data volumes are preserved across recreates — you don't lose history when rotating a password.

Production hardening

.env is the MVP approach. For production:

• Docker secrets — works well with Swarm mode.
• HashiCorp Vault — for dynamic credentials with TTLs.
• SOPS + age — encrypted .env files safe to commit.

These are documented in the Advanced deployment section (roadmap), not wired into the default OrcheStack install.