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

Coolify Deployment Guide

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

Deployment Options

The application supports two deployment approaches:

Option 1: Docker Compose (Recommended)

• Best for: Local development, consistent environments, simplified deployment
• See: Docker Compose Deployment Guide
• Key benefits:
  • Same containerized environment locally and in production
  • Built-in service orchestration and networking
  • Easy volume management for data persistence
  • Better debugging and log viewing

Option 2: Coolify with Nixpacks (Alternative)

• Best for: Existing Coolify installations, serverless deployments
• Key differences:
  • Uses Coolify's Nixpacks build system instead of Docker
  • Requires separate services setup in Coolify UI
  • Manual environment variable configuration per service

This guide covers Option 2 (Nixpacks). For Option 1 (Docker Compose), see the Docker Compose Deployment Guide.

Architecture Overview

The application consists of two Python services:

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

Coolify's built-in reverse proxy routes traffic:

• /api/* → Backend (port 12000)
• / → Frontend (port 12001)

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. 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 12000
8. Set Start Command to:

   uvicorn app.main:app --host 0.0.0.0 --port 12000
   

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	AI Allucanget
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 12001
7. Set Start Command to:

   gunicorn app.main:app --bind 0.0.0.0:12001 --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:12000 (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: 12000
• Path: /api/* → forward to backend

Frontend Proxy Rules

• Domain: ai.allucanget.biz
• Port: 12001
• 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:12000;
    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:12001;
    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

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:12000
• 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 "AI Allucanget")
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