ai.allucanget.biz/docs/deployment/coolify.md

Coolify Deployment Guide

This guide covers deploying ai.allucanget.biz using Coolify with Nixpacks from the repository https://git.allucanget.biz/allucanget/ai.allucanget.biz.git.

Architecture Overview

The application consists of two Python services:

Service	Framework	Port	Description
Backend	FastAPI + uvicorn	12015	REST API, auth, AI generation, DuckDB
Frontend	Flask + gunicorn	12016	SSR web UI, session auth, proxy to backend

Coolify's built-in reverse proxy routes traffic:

• /api/* → Backend (port 12015)
• / → Frontend (port 12016)

Prerequisites

• A Coolify instance (self-hosted or Cloud)
• Git repository pushed to https://git.allucanget.biz/allucanget/ai.allucanget.biz.git
• Domain configured to point to your Coolify server

Step 1: Create Backend Service

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

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

   gunicorn app.main:app --bind 0.0.0.0:12016 --workers 2 --timeout 120
   

8. Click Create Resource

Note: Nixpacks will automatically detect and install only the production dependencies from requirements.txt. 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

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

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
• 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

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:

   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:

   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:

# 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