allucanget/ai.allucanget.biz
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
abd61798c7ed44c4d23561a784894000a8146ea3
ai.allucanget.biz/docs/deployment/coolify.md
T

12 KiB
Raw Blame History

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: Coolify deployments, local development, consistent environments
  • Compose file: docker-compose.coolify.yml in Coolify, docker-compose.yml locally
  • Key benefits:
    • Same containerized services 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 both Coolify paths. Use Option 1 (Docker Compose) for new deployments. Use Option 2 (Nixpacks) only if you need separate Coolify services instead of one stack.

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

Option 1: Deploy with Docker Compose in Coolify

Use Coolify's Docker Compose resource with the dedicated compose file docker-compose.coolify.yml.

Step 1: Create Docker Compose Resource

  1. In Coolify, click Add Resource → Deploy a new resource → Docker Compose
  2. Connect your Git repository (git.allucanget.biz)
  3. Select the ai.allucanget.biz repository and main branch
  4. Set Compose File to docker-compose.coolify.yml
  5. Set Base Directory to /
  6. Select the frontend service as the public-facing service on port 12016
  7. Click Create Resource

Step 2: Configure Environment Variables

Add these in Coolify before first deploy:

Variable Service Example
OPENROUTER_API_KEY backend sk-or-v1-...
JWT_SECRET backend openssl rand -hex 32
APP_URL backend https://ai.allucanget.biz
APP_NAME backend AI Allucanget
CORS_ORIGINS backend https://ai.allucanget.biz
FLASK_SECRET_KEY frontend openssl rand -hex 32
BACKEND_URL frontend http://backend:12015

Step 3: Configure Domain and Proxy

  1. Attach domain ai.allucanget.biz to the frontend service on port 12016
  2. Enable Auto HTTPS in Coolify
  3. Coolify terminates TLS and forwards traffic directly to frontend:12016

No nginx service is needed in the Coolify stack. The frontend Flask app proxies /api/* calls to http://backend:12015 internally. Coolify's own reverse proxy handles external TLS termination.

Step 4: Persistent Storage

docker-compose.coolify.yml uses named volume app-data for DuckDB persistence at /app/data. No extra host bind mount needed for default setup.

Step 5: Deploy and Verify

  1. Start deployment in Coolify
  2. Confirm backend becomes healthy
  3. Open https://ai.allucanget.biz/health or proxied health route configured in Coolify
  4. Open main domain and verify frontend loads

Option 2: Deploy with Nixpacks in Coolify

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 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 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 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 "AI Allucanget")
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
Reference in New Issue View Git Blame Copy Permalink