# 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.