# ICOMAN deployment

## Environments

- Local: copy `.env.example` to `.env`; use SQLite or Docker; `APP_DEBUG=true` is acceptable only locally.
- Staging: use a separate database, Redis-backed queue/cache, `APP_DEBUG=false`, HTTPS, and staging-only credentials.
- Production: use a separate database and credentials, HTTPS, `APP_ENV=production`, `APP_DEBUG=false`, Redis queue/cache, secure/encrypted session cookies, and a non-root service account.

No secrets belong in Git. Configure `APP_KEY`, database credentials, mail credentials, `DB_PASSWORD`, `MYSQL_ROOT_PASSWORD`, and deployment SSH credentials in the host secret store or GitHub Environment secrets. GitHub deployments additionally require a pinned `DEPLOY_KNOWN_HOSTS` secret for SSH host-key verification.

## Delivery flow

`commit → lint → dependency audit → tests → image build → staging deploy → health smoke test → production approval/deploy → health smoke test`

The GitHub workflow deploys the `staging` branch to the protected `staging` environment and `main` to protected `production`. Configure required reviewers on the production environment before enabling deployments. The deploy script intentionally fails if required secrets are absent.

## Runtime processes

- Web: Nginx + PHP-FPM.
- Queue: run `queue:work` as a Supervisor-managed process using `deploy/supervisor/icoman-worker.conf`.
- Scheduler: install `deploy/cron/icoman-scheduler`, or run the Compose `scheduler` service.
- Health: `GET /healthz` validates database connectivity and returns `200 {"status":"ok"}`; it returns `503` when unavailable. Keep this endpoint behind normal edge rate limiting.

Run migrations before releasing application code that depends on them: `php artisan migrate --force`. Then refresh config, route, and view caches and restart queue workers.

## Backup and restore

1. Nightly encrypted database dumps, retained for 35 days, plus monthly copies retained for 12 months.
2. Back up private `storage/app` documents and generated card assets with the database dump’s timestamp.
3. Store backups in a separate account/region with least-privilege write access; test a restore to staging quarterly.
4. Record restore time, integrity checks, and the target recovery point. Never copy `.env` files into backups shared outside the secret-management boundary.