erp-nutzfahrzeuge/deploy/coolify-config.md

# Coolify Deployment Configuration — ERP Nutzfahrzeuge

---

## Overview

This document describes how to deploy the ERP Nutzfahrzeuge system on Coolify using Docker Compose.

The system consists of 4 services:

| Service | Image | Port | Health Check |
|---------|-------|------|-------------|
| Backend | Custom (Python 3.13-slim) | 8000 | `GET /api/v1/health` |
| Frontend | Custom (Node 18-alpine) | 3000 | `GET /` |
| PostgreSQL | `postgres:16-alpine` | 5432 | `pg_isready` |
| Redis | `redis:7-alpine` | 6379 | `redis-cli ping` |

---

## Coolify Resource Setup

### Step 1: Create Resource

1. In Coolify, create a new resource
2. Select **Docker Compose** as the resource type
3. Connect your Forgejo/Git repository
4. Set the base directory to the project root
5. Coolify will detect `docker-compose.yml` automatically

### Step 2: Configure Environment Variables

1. Navigate to resource → **Environment Variables**
2. Add all variables from `.env.example` (see `deploy/env.md` for descriptions)
3. **Critical variables:**
   - `JWT_SECRET` — generate with `openssl rand -hex 32`
   - `POSTGRES_PASSWORD` — strong password for database
   - `CORS_ORIGINS` — production frontend URL (e.g., `https://erp.your-domain.com`)
   - `NEXT_PUBLIC_API_URL` — production backend URL (e.g., `https://api.your-domain.com/api/v1`)
4. **Optional but feature-dependent:**
   - `OPENROUTER_API_KEY` — required for AI features (OCR, retouch, copilot)
   - `MOBILE_DE_API_KEY` + `MOBILE_DE_SELLER_ID` — required for mobile.de integration
5. Click **Save** and redeploy

### Step 3: Configure Health Check

In the resource settings:

| Setting | Value |
|---------|-------|
| Health check path | `/api/v1/health` |
| Health check port | `8000` |
| Health check interval | `30s` |
| Health check timeout | `5s` |
| Health check retries | `3` |

> **Note:** The health check targets the backend service. Docker Compose health checks are also defined per-service in `docker-compose.yml`.

### Step 4: Configure Persistent Storage

Docker Compose volumes are defined in `docker-compose.yml`:

| Volume | Mount Point | Purpose |
|--------|-------------|---------|
| `uploads` | `/data/uploads` (backend) | User file uploads (images, documents) |
| `pgdata` | `/var/lib/postgresql/data` (postgres) | Database data |
| `redisdata` | `/data` (redis) | Redis persistence (AOF) |

In Coolify:
1. Ensure persistent storage is enabled for the resource
2. Verify volume names match the compose file
3. For production, consider using a managed PostgreSQL instance instead of the containerized one

### Step 5: Configure Domains / Routing

1. **Backend API:**
   - Set domain: `api.your-domain.com` (or subpath)
   - Port: `8000`
   - This is the primary entry point for Coolify health checks

2. **Frontend:**
   - Set domain: `erp.your-domain.com` (or root domain)
   - Port: `3000`
   - Next.js standalone server

3. **CORS:**
   - Set `CORS_ORIGINS` to the frontend domain
   - Set `NEXT_PUBLIC_API_URL` to the backend domain

### Step 6: Deploy

1. Click **Deploy** in Coolify
2. Wait for all services to build and start
3. Verify health checks pass (green status for all services)
4. Test endpoints:
   - `GET https://api.your-domain.com/api/v1/health` → 200 `{"status":"ok"}`
   - `GET https://erp.your-domain.com/` → 200 (frontend loads)
   - `GET https://api.your-domain.com/openapi.json` → 200 (API schema)

---

## Coolify Service Type

- **Type:** Docker Compose (multi-service)
- **Compose file:** `docker-compose.yml` (project root)
- **Build:** Coolify builds images from `backend/Dockerfile` and `frontend/Dockerfile`
- **Pre-built images:** `postgres:16-alpine`, `redis:7-alpine`

---

## Port Mapping

| Service | Internal Port | External Port | Notes |
|---------|---------------|---------------|-------|
| Backend | 8000 | 8000 | FastAPI + uvicorn (4 workers) |
| Frontend | 3000 | 3000 | Next.js standalone server |
| PostgreSQL | 5432 | — (internal only) | Not exposed externally |
| Redis | 6379 | — (internal only) | Not exposed externally |

> In Coolify, only expose backend (8000) and frontend (3000) via domains. PostgreSQL and Redis should remain internal to the Docker network.

---

## Build Configuration

### Backend
- **Base image:** `python:3.13-slim`
- **System packages:** libpango, libcairo, libjpeg, libpng (for WeasyPrint + Pillow)
- **Python venv:** `/opt/venv`
- **Entry:** `uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4`

### Frontend
- **Base image:** `node:18-alpine` (multi-stage)
- **Build:** `npm ci && npm run build` (standalone output)
- **Entry:** `node server.js`
- **Requires:** `output: 'standalone'` in `next.config.js`

---

## Post-Deploy Verification

1. All 4 containers are running and healthy
2. `GET /api/v1/health` → 200 `{"status":"ok"}`
3. Frontend loads at production URL
4. Login flow works: `POST /api/v1/auth/login`
5. CORS headers present for frontend origin
6. No errors in container logs
7. File uploads work (test upload to `/data/uploads`)
8. Database queries return expected data

---

## Troubleshooting

| Issue | Cause | Solution |
|-------|-------|----------|
| Backend health check fails | DB not ready | Check `postgres` container health; increase `start_period` |
| WeasyPrint errors | Missing system libs | Verify `libpango`, `libcairo` installed in backend image |
| Frontend build fails | Missing `output: 'standalone'` | Add `output: 'standalone'` to `next.config.js` |
| CORS errors | Wrong `CORS_ORIGINS` | Set to exact frontend domain (no trailing slash) |
| AI features fail | Missing `OPENROUTER_API_KEY` | Set API key in Coolify environment variables |
| mobile.de fails | Missing credentials | Set `MOBILE_DE_API_KEY` and `MOBILE_DE_SELLER_ID` |

---

## Rollback

See `deploy/rollback.md` for the full rollback procedure.

Quick rollback in Coolify:
1. Navigate to resource → **Deployments**
2. Find last known-good deployment
3. Click **Redeploy**
4. Verify health check passes