MOHPortal/docs/COOLIFY_SANDBOX_CHECKLIST.md

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:

  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:

  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.