# 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 `12000` externally for the frontend (or map to 80/443 via Coolify's proxy).
   - 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.