MOHPortal/docs/INFRA_PLANNING.md

Infrastructure Planning Notes

This document captures next steps for adopting Coolify and Gitea CI/registry in a controlled, reproducible way.

1. Coolify Rollout Strategy

1. Create a disposable sandbox first

   • Spin up a local VM (or an inexpensive VPS) dedicated to Coolify experiments.
   • Use it to run the installer, attach your Gitea instance, and deploy this repository end-to-end.
   • Exercise high-value features (PR previews, environment variables, health checks) without risking production downtime.

2. Keep the sandbox long-term

   • After production goes live, retain the sandbox as a staging ground for platform upgrades and new service integrations.
   • Rehearse backup/restore workflows and new release rollouts here before promoting changes.

3. Provision production infrastructure once comfortable

   • Select a control-plane VPS with at least 2 vCPUs, 4–8 GB RAM, and SSD storage; add additional app servers later if demand grows.
   • Repeat the installation using hardened settings (firewall rules, fail2ban, automated backups).
   • Point the production Coolify instance at the same container registry and Gitea repository tested in the sandbox.

2. Deployment Checklist for Each Environment

• Link Gitea and verify the CI workflow pushes backend/frontend images with commit tags.
• Import this repository in Coolify and target deploy/coolify/docker-compose.yml.
• Set environment variables (BACKEND_IMAGE, FRONTEND_IMAGE, POSTGRES_*, JWT_SECRET, REACT_APP_API_URL).
• Configure post-deploy hooks (npm run migrate, optionally npm run seed).
• Test PR preview environments end-to-end (create PR, verify preview URL, merge, confirm teardown).
• Validate monitoring/alerting (Coolify health checks, optional external uptime monitor).

3. Gitea CI & Runner Guidance

• Use a dedicated runner VM or lightweight VPS. Keeping the runner separate from your Gitea host avoids resource contention and lets you scale build capacity independently.
• Install the Gitea Actions Runner via Docker or binary, register it against your Gitea instance, and grant network access to both the registry and Coolify endpoints.
• Start with a single runner sized similarly to the sandbox Coolify VM (2 vCPU / 4 GB RAM). Add more runners or scale up as build concurrency increases.
• Store registry credentials (REGISTRY_HOST, REGISTRY_USERNAME, REGISTRY_PASSWORD) as encrypted Gitea secrets so workflows can push images automatically.

4. Container Registry Considerations

• Gitea ships with a built-in registry; enable it if you want an all-in-one solution. Alternatively, use another OCI registry (Harbor, GitHub Container Registry, Docker Hub) if already available.
• Whichever registry you choose, ensure:
  • TLS certificates are valid and trusted by both the runner and Coolify hosts.
  • Storage quotas can handle CI build artifacts and PR-preview images.
  • Access tokens have scope for both push (CI) and pull (Coolify).

5. Learning Path & Practice Drills

• Walkthroughs to complete in the sandbox:

  1. Fresh Coolify install + first deployment of this app.
  2. PR preview flow from Gitea branch → CI build → Coolify preview → teardown.
  3. Coolify backup/restore exercise (export settings, recreate on new VM).
  4. Registry credential rotation (update secret, trigger new deploy).

• Reference material:

  • Coolify docs (install, server management, multi-server guides).
  • Gitea Actions documentation for runner installation and secret management.
  • OCI registry basics (tags, authentication, retention policies).

Completing these drills will build confidence before you commit production traffic to the platform.