Sprint 24 Actual Staging Deployment and QA

Use this when: preparing or auditing the first actual staging deployment for https://staging-app.submicrons.net.

Chosen Staging Target

Sprint 23 already prepared Dockerfiles and docker-compose.staging.yml. Until a managed platform is explicitly selected, Sprint 24 uses the practical assumption of a VPS or Docker host running:

1. web container on internal port 3000.
2. docs container on internal port 3001.
3. PostgreSQL staging database outside the application containers or as a managed staging database.
4. Reverse proxy or platform load balancer terminating HTTPS for staging-app.submicrons.net.

This is staging only. Production deployment remains out of scope.

Deployment Steps

1. Provision a staging-only PostgreSQL database.
2. Create an untracked .env.staging from .env.staging.example.
3. Replace placeholders in the host secret store only.
4. Keep all external integration flags disabled.
5. Run environment validation.
6. Build containers with Dockerfile.web and Dockerfile.docs.
7. Apply migrations with deploy-mode migrations.
8. Run seed only after confirming the target database is staging/demo.
9. Start docker compose -f docker-compose.staging.yml up -d --build.
10. Check /api/health, /api/ready, login, docs, and smoke tests.

Rollback Steps

1. Stop rollout and notify the owner.
2. Preserve logs and the failing image/tag.
3. Revert to the previous image or branch.
4. Restore the database only after approval and only from a verified staging backup.
5. Re-run /api/health, /api/ready, login, smoke tests, and manager rehearsal.

Environment Requirements

• APP_ENV=staging
• APP_URL=https://staging-app.submicrons.net
• BETTER_AUTH_URL=https://staging-app.submicrons.net
• AUTH_TRUST_HOST=true
• staging-only DATABASE_URL
• external integration flags set to false
• no production secrets
• no real customer exports or private import files

Domain and HTTPS

Create DNS for staging-app.submicrons.net to point at the staging reverse proxy or platform hostname. HTTPS is required for staging auth cookies. Staging redirects must stay relative or target the staging host; they must not redirect to localhost.

Current Sprint 24 Status

The repository is prepared for this target locally. This Codex session did not deploy the public staging host because no VPS/platform credentials, DNS access, TLS configuration, or staging database secret were available in the workspace.