89 lines
4.6 KiB
Markdown
89 lines
4.6 KiB
Markdown
# 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.
|