From 615b842b031b4be105372698a1769283e6646964 Mon Sep 17 00:00:00 2001 From: zwitschi Date: Wed, 29 Apr 2026 17:44:35 +0200 Subject: [PATCH] feat: streamline Coolify deployment guide by removing redundant steps and clarifying environment variable setup --- docs/deployment/coolify.md | 185 ------------------------------------- 1 file changed, 185 deletions(-) diff --git a/docs/deployment/coolify.md b/docs/deployment/coolify.md index ead9de4..354fac3 100644 --- a/docs/deployment/coolify.md +++ b/docs/deployment/coolify.md @@ -173,188 +173,3 @@ All required environment variables: - [ ] Domain names configured - [ ] Health checks passing - [ ] Logs reviewed for errors - -1. In Coolify, click **Add Resource** → **Deploy a new resource** → **Git** -2. Connect your Git repository (`git.allucanget.biz`) -3. Select the `ai.allucanget.biz` repository -4. Choose the `main` branch -5. Set **Build Pack** to `nixpacks` -6. **CRITICAL: Set Base Directory to `/backend`** — this tells Nixpacks to look in the `backend/` subdirectory for `requirements.txt` and the Python application -7. Set **Ports Exposed** to `12015` -8. Set **Start Command** to: - - ```txt - uvicorn app.main:app --host 0.0.0.0 --port 12015 - ``` - -9. Click **Create Resource** - -> **Important:** Nixpacks copies the **contents** of the Base Directory to `/app/` in the container. When Base Directory is `/backend`, the `backend/` folder wrapper is removed — only `app/`, `tests/`, and `requirements.txt` are copied. Therefore the start command uses `app.main:app` (not `backend.app.main:app`). - -### Backend Environment Variables - -Add these as **Runtime** environment variables in Coolify: - -| Variable | Description | Example | -| -------------------- | ------------------------------------ | ------------------------------------ | -| `OPENROUTER_API_KEY` | OpenRouter API key for AI generation | `sk-or-v1-...` | -| `JWT_SECRET` | Secret key for JWT token signing | Generate with `openssl rand -hex 32` | -| `APP_URL` | Public URL of the backend | `https://api.ai.allucanget.biz` | -| `APP_NAME` | Application name | `All You Can GET AI` | -| `CORS_ORIGINS` | Comma-separated allowed origins | `https://ai.allucanget.biz` | - -## Step 2: Create Frontend Service - -1. In Coolify, click **Add Resource** → **Deploy a new resource** → **Git** -2. Select the same repository -3. Choose the `main` branch -4. Set **Build Pack** to `nixpacks` -5. **CRITICAL: Set Base Directory to `/frontend`** — this tells Nixpacks to look in the `frontend/` subdirectory for `requirements.txt` and the Python application -6. Set **Ports Exposed** to `12016` -7. Set **Start Command** to: - - ```txt - gunicorn app.main:app --bind 0.0.0.0:12016 --workers 2 --timeout 120 - ``` - -8. Click **Create Resource** - -> **Note:** The frontend uses `requirements.txt` for production dependencies and `requirements-dev.txt` for development dependencies (like pytest). Nixpacks will automatically detect and install only the production dependencies. -> **Important:** Nixpacks copies the **contents** of the Base Directory to `/app/` in the container. When Base Directory is `/frontend`, the `frontend/` folder wrapper is removed — only `app/`, `tests/`, and `requirements.txt` are copied. Therefore the start command uses `app.main:app` (not `frontend.app.main:app`). - -### Frontend Environment Variables - -Add these as **Runtime** environment variables in Coolify: - -| Variable | Description | Example | -| ------------------ | ----------------------------------------- | --------------------------------------------------------------- | -| `FLASK_SECRET_KEY` | Flask session cookie signing key | Generate with `openssl rand -hex 32` | -| `BACKEND_URL` | Internal URL to reach the backend service | `http://localhost:12015` (or use Coolify's internal networking) | - -## Step 3: Configure Reverse Proxy - -Coolify provides a built-in reverse proxy. Configure routing rules: - -### Backend Proxy Rules - -- **Domain**: `api.ai.allucanget.biz` (or subdomain of your choice) -- **Port**: `12015` -- **Path**: `/api/*` → forward to backend - -### Frontend Proxy Rules - -- **Domain**: `ai.allucanget.biz` -- **Port**: `12016` -- **Path**: `/` → forward to frontend - -### Nginx Configuration (Optional) - -If you need custom Nginx configuration, create `nginx/coolify.conf`: - -```nginx -# Reverse proxy configuration for Coolify -# This file is for reference — Coolify's built-in proxy handles routing - -# Backend API proxy -location /api/ { - proxy_pass http://backend:12015; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; -} - -# Frontend proxy -location / { - proxy_pass http://frontend:12016; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; -} -``` - -## Step 4: SSL/TLS - -Enable HTTPS in Coolify for both services: - -1. Go to each service's settings -2. Enable **Auto HTTPS** (Let's Encrypt) -3. Configure domain names -4. Coolify automatically handles certificate renewal - -## Step 5: Persistent Storage (Optional) - -If you want to persist DuckDB data: - -1. In Coolify, go to the **Backend** service -2. Navigate to **Persistent Storage** -3. Add a volume mount: - - **Host Path**: `/data` (or any path on the host) - - **Container Path**: `/app/data` - - **Type**: `Bind Mount` or `Volume` - -## Troubleshooting - -### Docker Compose deployment fails in Coolify - -- Verify Coolify uses `docker-compose.coolify.yml`, not local `docker-compose.yml` -- Verify public domain points to `frontend` service on port `12016` -- Do not add `nginx` to the Coolify stack — bind-mounting a local config file will fail since the file doesn't exist on the Coolify server - -### Backend healthcheck stays unhealthy - -- Check backend logs in Coolify -- Verify `OPENROUTER_API_KEY` and `JWT_SECRET` are set -- Verify volume mount at `/app/data` is writable - -### Backend won't start - -- Check that `OPENROUTER_API_KEY` is set -- Verify `JWT_SECRET` is a sufficiently long random string -- Check logs in Coolify's **Logs** tab - -### Frontend can't reach backend - -- Ensure `BACKEND_URL` points to the correct internal URL -- If both services are on the same Coolify server, use `http://localhost:12015` -- Check that the backend service is running and healthy - -### CORS errors - -- Set `CORS_ORIGINS` to include your frontend domain -- Example: `https://ai.allucanget.biz` - -### Nixpacks build fails - -- Verify the base directory is correct (`/backend` or `/frontend`) -- Check that `requirements.txt` exists in the base directory -- Review build logs in Coolify - -## Environment Variable Summary - -All required environment variables: - -| Variable | Service | Required | -| -------------------- | -------- | ------------------------------------- | -| `OPENROUTER_API_KEY` | Backend | Yes | -| `JWT_SECRET` | Backend | Yes | -| `APP_URL` | Backend | Yes | -| `APP_NAME` | Backend | No (defaults to "All You Can GET AI") | -| `CORS_ORIGINS` | Backend | Yes | -| `FLASK_SECRET_KEY` | Frontend | Yes | -| `BACKEND_URL` | Frontend | Yes | - -## Deployment Checklist - -- [ ] Repository pushed to Git -- [ ] For Docker Compose: Coolify resource uses `docker-compose.coolify.yml` -- [ ] For Docker Compose: domain points to `frontend` service on port `12016` -- [ ] Backend service created with correct base directory (`/backend`) -- [ ] Backend environment variables configured -- [ ] Frontend service created with correct base directory (`/frontend`) -- [ ] Frontend environment variables configured -- [ ] SSL certificates enabled -- [ ] Domain names configured -- [ ] Health checks passing -- [ ] Logs reviewed for errors