Prepare CI and deployment scaffolding

docs/COOLIFY_DEPLOYMENT.md

@@ -0,0 +1,88 @@
+# Coolify Deployment Guide
+
+This guide summarizes how to promote MerchantsOfHope-SupplyANdDemandPortal from Gitea CI to a Coolify-managed environment.
+
+## Prerequisites
+
+- A Coolify instance with access to your container registry.
+- Gitea repository hosting this project, with Gitea Actions enabled and a runner that supports Docker builds.
+- Registry credentials (username, password/access token, hostname) for publishing backend and frontend images.
+- Optional: a managed PostgreSQL instance. The provided Compose file creates one automatically if you do not have an external database.
+
+## Overview
+
+1. Gitea Actions builds and (optionally) pushes backend and frontend images when changes land on the `main` branch.
+2. Coolify pulls those images and runs the stack defined in `deploy/coolify/docker-compose.yml`.
+3. Post-deploy hooks run database migrations so the schema matches the current code.
+
+## Configure Gitea CI
+
+Secrets required by `.gitea/workflows/ci.yml`:
+
+| Secret | Purpose |
+| ------ | ------- |
+| `REGISTRY_HOST` | Hostname of the registry (e.g., `registry.example.com`). Leave blank to skip pushing. |
+| `REGISTRY_USERNAME` | Registry account used to push images. |
+| `REGISTRY_PASSWORD` | Token/password for the account. |
+
+The workflow publishes two images using the commit SHA as the tag:
+
+- `${REGISTRY_HOST}/merchantsofhope-supplyanddemandportal-backend:<sha>`
+- `${REGISTRY_HOST}/merchantsofhope-supplyanddemandportal-frontend:<sha>`
+
+Expose the tag you want Coolify to deploy by either:
+
+- Creating a Git tag/release and configuring Coolify to deploy tags, or
+- Using Coolify's "Deploy on new commit" option and translating the latest SHA into the `BACKEND_IMAGE` / `FRONTEND_IMAGE` environment variables.
+
+## Prepare the Coolify Stack
+
+1. **Add the repository**
+   - In Coolify, create a new *Docker Compose Application*.
+   - Connect your Gitea account and select this repository.
+   - Set the Compose path to `deploy/coolify/docker-compose.yml`.
+
+2. **Set environment variables** (use the UI or a `.env` file uploaded to Coolify):
+
+   | Variable | Description |
+   | -------- | ----------- |
+   | `BACKEND_IMAGE` | Fully qualified image tag published by CI (e.g., `registry.example.com/merchantsofhope-supplyanddemandportal-backend:abcd123`). |
+   | `FRONTEND_IMAGE` | Fully qualified image tag published by CI. |
+   | `POSTGRES_DB` | Database name (defaults to `merchantsofhope_supplyanddemandportal`). |
+   | `POSTGRES_USER` | Database user (defaults to `merchantsofhope`). |
+   | `POSTGRES_PASSWORD` | **Required.** Strong password for the database. |
+   | `JWT_SECRET` | **Required.** Secret key for backend token signing. |
+   | `REACT_APP_API_URL` | URL the frontend uses to reach the backend (defaults to the internal service URL). |
+
+   Configure any additional secrets used by your environment (mail providers, analytics, etc.).
+
+3. **Networking and ports**
+   - Expose port `3000` externally for the frontend.
+   - Optionally expose `3001` if you want direct API access; otherwise rely on the frontend or internal services.
+   - Attach the application to an HTTPS domain using Coolify's built-in proxy configuration.
+
+4. **Database migrations**
+   - Add a post-deployment command in Coolify to run `npm run migrate` inside the backend container:
+     ```bash
+     docker compose exec merchantsofhope-supplyanddemandportal-backend npm run migrate
+     ```
+   - If you maintain seed data, run `npm run seed` the same way.
+
+5. **Zero-downtime considerations**
+   - Enable health checks in Coolify so new backend containers pass readiness before switching traffic.
+   - Consider scaling the backend to more than one replica once load requires it.
+
+## Local Development Parity
+
+- Use `docker-compose up --build` to replicate the production stack locally.
+- Keep `.env` aligned with the variables described above so Gitea CI, local development, and Coolify deployment share the same configuration keys.
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+| ------- | ------------ | --- |
+| Backend container exits immediately | Missing or incorrect `DATABASE_URL`/`POSTGRES_*` values | Verify Coolify environment variables and that the database service is healthy. |
+| Frontend cannot reach API | `REACT_APP_API_URL` points to an unreachable host | Adjust to Coolify-provided domain or internal service URL. |
+| CI cannot push images | Registry secrets not configured or incorrect permissions | Update `REGISTRY_*` secrets and ensure the runner has network access to the registry. |
+
+For additional customization (e.g., connecting to an external PostgreSQL cluster or adding Redis), copy `deploy/coolify/docker-compose.yml` and extend it with your required services.