Document infrastructure rollout plan

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.