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

# Coolify Deployment Guide

This guide covers deploying `ai.allucanget.biz` using [Coolify](https://coolify.io) 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:

   ```txt
   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:

   ```txt
   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`:

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