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