diff --git a/docs/INFRA_PLANNING.md b/docs/INFRA_PLANNING.md new file mode 100644 index 0000000..f597976 --- /dev/null +++ b/docs/INFRA_PLANNING.md @@ -0,0 +1,58 @@ +# 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.