chore: sync infra docs and coverage

docs/COOLIFY_SANDBOX_CHECKLIST.md

@@ -0,0 +1,74 @@
+# Coolify Sandbox Checklist
+
+Use this guide to spin up and maintain the disposable Coolify sandbox that mirrors production deployment flows for the MerchantsOfHope Supply & Demand Portal.
+
+## 1. Provision the Sandbox Host
+- Choose a fresh VM/VPS with at least 2 vCPU, 4 GB RAM, and 40 GB SSD; Ubuntu 22.04 LTS is the default target.
+- Allocate a dedicated subdomain (example: `coolify-sandbox.merchantsofhope.org`) and, optionally, a wildcard (`*.apps.coolify-sandbox.merchantsofhope.org`) for preview deployments.
+- Open inbound ports 22/tcp (SSH), 80/443 (HTTP/HTTPS), and 8000 (initial Coolify UI before proxy is enabled).
+
+## 2. Prepare the OS
+- Update packages: `apt update && apt upgrade -y` (adjust for distro).
+- Install basics if missing: `curl`, `wget`, `git`, `jq`, `ufw`.
+- Enable firewall rules that keep ports 22, 80, 443, and 8000 reachable.
+
+## 3. Install Coolify
+- Log in as `root` (or use `sudo -E`) and run the official quick installer:
+  ```bash
+  curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
+  ```
+- Create the initial admin account immediately after the installer prints the access URL.
+- Optional: preseed credentials during install with `ROOT_USERNAME`, `ROOT_USER_EMAIL`, and `ROOT_USER_PASSWORD` environment variables.
+
+## 4. Post-Install Hardening
+- Add an A record for the chosen hostname pointing at the VM; set up a wildcard record if PR previews are desired.
+- In the Coolify dashboard, enable HTTPS via the bundled Traefik proxy (Let’s Encrypt).
+- Change the default SSH port if desired and ensure the Coolify-generated SSH key is present at `/data/coolify/ssh/keys`.
+- Configure automatic upgrades to "manual" so upgrades are rehearsed here before production.
+
+## 5. Connect Integrations
+- **Gitea**: add a Gitea integration in Coolify (Settings → Git Sources) using a service account or personal access token with repo read access.
+- **Container registry**: decide between the built-in Gitea registry or an external registry. Create a robot/service account with pull permissions for Coolify and push permissions for CI.
+- **Runner location**: reuse the workstation’s runner for now; add the dedicated runner VM later if you need isolation or more concurrency.
+- Store registry credentials in Coolify as a global secret group (Settings → Secrets).
+
+## 6. Import the Application
+- Create a new *Docker Compose Application* in Coolify.
+- Repository: `MerchantsOfHope-SupplyANdDemandPortal`.
+- Compose path: `deploy/coolify/docker-compose.yml`.
+- Define environment variables to match the Compose file:
+  - `BACKEND_IMAGE`, `FRONTEND_IMAGE` (full image references that CI builds and pushes).
+  - `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`.
+  - `JWT_SECRET`.
+  - `REACT_APP_API_URL` (use the internal backend URL for now; update to public URL after proxying).
+- Configure service health checks and attach the Coolify-provided domain to the frontend service.
+
+## 7. Post-Deployment Hooks
+- Add a hook that runs after each deploy:
+  ```bash
+  docker compose exec merchantsofhope-supplyanddemandportal-backend npm run migrate
+  ```
+- Optionally add a second hook for seeding: `npm run seed`.
+
+## 8. Validate the Pipeline
+- In Gitea, set `REGISTRY_HOST`, `REGISTRY_USERNAME`, and `REGISTRY_PASSWORD` secrets so the `docker-images` job publishes images on the `main` branch.
+- Run a test push to `main` (or re-run the workflow) and capture the SHA-based image tag from the workflow summary.
+- Update the Coolify application’s `BACKEND_IMAGE` and `FRONTEND_IMAGE` to the new tags, then trigger a deployment.
+- Verify:
+  - Database migrations succeed.
+  - Frontend loads via the Coolify-managed domain and can hit the backend.
+  - Logs are clean (`docker compose logs -f` in Coolify shell).
+
+## 9. Sandbox Maintenance
+- Schedule a weekly refresh: pull the latest `main`, trigger CI, redeploy in Coolify.
+- Practice backups: export Coolify configuration and snapshot the PostgreSQL volume.
+- Test upgrades here before promoting to production (run the installer script to upgrade, validate, then replicate in production).
+- Document any manual tweaks in this repository (`docs/INFRA_PLANNING.md` or a dedicated runbook) so production setup stays reproducible.
+
+## 10. Ready for Production When…
+- CI → Registry → Coolify deploy loop runs without manual intervention.
+- Environment variables match production values (except secrets).
+- Backup and restore drills succeed in the sandbox.
+- Team confirms Coolify access, deployment permissions, and preview flows.
+
+Track completion by checking off each section above; update this checklist with lessons learned as the sandbox evolves.