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

Gitea Actions builds and (optionally) pushes backend and frontend images when changes land on the main branch.
Coolify pulls those images and runs the stack defined in deploy/coolify/docker-compose.yml.
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

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.

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

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.
Database migrations
- Add a post-deployment command in Coolify to run npm run migrate inside the backend container:
```
docker compose exec merchantsofhope-supplyanddemandportal-backend npm run migrate
```
- If you maintain seed data, run npm run seed the same way.
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.

4.6 KiB Raw Blame History