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

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

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 nginx service as the public-facing service on port 80
  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:12000

Step 3: Configure Domain and Proxy

  1. Attach domain ai.allucanget.biz to nginx service
  2. Enable Auto HTTPS in Coolify
  3. Let Coolify terminate TLS and forward traffic to nginx:80

docker-compose.coolify.yml does not publish host ports 80/443. This avoids conflicts with Coolify's own proxy while keeping backend and frontend reachable over internal Docker network.

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

Docker Compose deployment fails in Coolify

  • Verify Coolify uses docker-compose.coolify.yml, not local docker-compose.yml
  • Verify public domain points to nginx service on port 80
  • Do not publish host ports 80:80 or 443:443 inside Coolify stack

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: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
  • For Docker Compose: Coolify resource uses docker-compose.coolify.yml
  • For Docker Compose: domain points to nginx service on port 80
  • 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