allucanget/ai.allucanget.biz
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor application ports to 12000 for backend and 12001 for frontend; update documentation and configuration files accordingly

Browse Source 
Co-authored-by: Copilot <copilot@github.com>
This commit is contained in:
zwitschi
2026-04-28 10:20:58 +02:00
parent 80999b3659
commit 5371bdce3b
11 changed files with 506 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/7-deployment-view.md
+73 -11
View File
@@ -8,13 +8,13 @@ Describes:
## Infrastructure Level 1
```text
┌─────────────────────────────────────────────┐
│ Host / VM │
│ ┌─────────────┐ ┌─────────────────────┐ │
│ │ frontend │ │ backend │ │
│ │ (Flask) │ │ (FastAPI) │ │
│ │ :5000 │ │ :12000 │ │
│ └──────┬──────┘ └──────────┬──────────┘ │
┌────────────────────────────────────────────┐
│ Host / VM │
│ ┌─────────────┐ ┌────────────────────┐ │
│ │ frontend │ │ backend │ │
│ │ (Flask) │ │ (FastAPI) │ │
│ │ :12001 │ │ :12000 │ │
│ └──────┬──────┘ └─────────┬──────────┘ │
│ │ │ │
│ └────────┬──────────┘ │
│ │ │
@@ -22,7 +22,7 @@ Describes:
│ │ db (DuckDB) │ │
│ │ data/app.db │ │
│ └────────────────┘ │
└─────────────────────────────────────────────┘
└────────────────────────────────────────────┘
```
**Motivation:** All three components run on a single VM (or as Docker containers) for simplicity and low operational overhead.
@@ -33,12 +33,74 @@ Describes:
| Building Block | Container / Process | Port |
| --------------- | ---------------------------- | ----- |
| Flask frontend | `frontend` | 5000 |
| Flask frontend | `frontend` | 12001 |
| FastAPI backend | `backend` | 12000 |
| DuckDB | File on host (`data/app.db`) | — |
## Infrastructure Level 2
### Docker Compose (alternative)
### Docker Compose (Recommended for Development & Production)
All three services can be run with `docker compose up`. The `backend` mounts the `data/` volume for DuckDB persistence.
All services are containerized and orchestrated with `docker compose`:
```text
┌─────────────────────────────────────────────────────────────┐
│ Docker Host / VM │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Docker Network: app-network (bridge) │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ Backend Container (FastAPI) │ │ │
│ │ │ - Port: 12000 │ │ │
│ │ │ - Service Name: backend │ │ │
│ │ │ - Volume Mount: /app/data ← host/data/ │ │ │
│ │ ├──────────────────────────────────────────────┤ │ │
│ │ │ Frontend Container (Flask) │ │ │
│ │ │ - Port: 12001 │ │ │
│ │ │ - Service Name: frontend │ │ │
│ │ │ - Depends on: backend (health check) │ │ │
│ │ ├──────────────────────────────────────────────┤ │ │
│ │ │ Nginx Container (Reverse Proxy) │ │ │
│ │ │ - Port: 80 (HTTP), 443 (HTTPS) │ │ │
│ │ │ - Config: nginx/docker-compose.conf │ │ │
│ │ │ - Routes: /api/* → backend:12000 │ │ │
│ │ │ / → frontend:12001 │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
│ ▲ │
│ Host Port Bindings │
│ 80:80, 443:443, 12000:12000, 12001:12001 │
└─────────────────────────────────────────────────────────────┘
│
Users / Internet
```
**Deployment Steps:**
1. Ensure Docker and Docker Compose are installed
2. Create `.env` with required environment variables
3. Run: `docker compose up --build`
4. Access via browser at `http://localhost:12001` or through Nginx at `http://localhost:80`
**Benefits:**
- **Consistency**: Same containerized environment across development, testing, and production
- **Simplicity**: Single command to start entire stack
- **Portability**: Run on any system with Docker installed
- **Persistence**: DuckDB data survives container restarts via volume mounts
- **Networking**: Service names enable automatic DNS resolution (backend:12000, frontend:12001)
- **Observability**: Easy logging with `docker compose logs`
**See**: [Docker Compose Deployment Guide](./deployment/docker-compose.md) for detailed instructions.
### Coolify (Alternative for Existing Deployments)
If using Coolify instead of Docker Compose:
1. **Backend Service**: Nixpacks build with base directory `/backend`, port 12000
2. **Frontend Service**: Nixpacks build with base directory `/frontend`, port 12001
3. **Reverse Proxy**: Coolify's built-in proxy or custom Nginx config
4. **Data Persistence**: Volume mount at `/app/data` for DuckDB
**Note**: Both services must be on the same Coolify server or cluster for service-to-service communication via `http://localhost:12000` or service DNS names (depending on Coolify's networking setup).
**See**: [Coolify Deployment Guide](./deployment/coolify.md) for detailed instructions.
docs/deployment/coolify.md
+30 -6
View File
@@ -2,6 +2,30 @@
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**: Local development, consistent environments, simplified deployment
- **See**: [Docker Compose Deployment Guide](./docker-compose.md)
- **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](./docker-compose.md).
## Architecture Overview
The application consists of two Python services:
@@ -9,12 +33,12 @@ The application consists of two Python services:
| Service | Framework | Port | Description |
| -------- | ----------------- | ----- | ------------------------------------------ |
| Backend | FastAPI + uvicorn | 12000 | REST API, auth, AI generation, DuckDB |
| Frontend | Flask + gunicorn | 5000 | SSR web UI, session auth, proxy to backend |
| 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 5000)
- `/` → Frontend (port 12001)
## Prerequisites
@@ -58,10 +82,10 @@ Add these as **Runtime** environment variables in Coolify:
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 `5000`
6. Set **Ports Exposed** to `12001`
7. Set **Start Command** to:
```txt
gunicorn app.main:app --bind 0.0.0.0:5000 --workers 2 --timeout 120
gunicorn app.main:app --bind 0.0.0.0:12001 --workers 2 --timeout 120
```
8. Click **Create Resource**
@@ -91,7 +115,7 @@ Coolify provides a built-in reverse proxy. Configure routing rules:
### Frontend Proxy Rules
- **Domain**: `ai.allucanget.biz`
- **Port**: `5000`
- **Port**: `12001`
- **Path**: `/` → forward to frontend
### Nginx Configuration (Optional)
@@ -113,7 +137,7 @@ location /api/ {
# Frontend proxy
location / {
proxy_pass http://frontend:5000;
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;
docs/deployment/docker-compose.md
+243
View File
@@ -0,0 +1,243 @@
# Docker Compose Deployment Guide
This guide explains how to deploy the AI application locally using Docker Compose.
## Overview
Docker Compose provides a convenient way to:
- **Develop locally** with the same containerized environment used in production
- **Manage services** as a single stack (backend, frontend, and Nginx)
- **Persist data** using volume mounts
- **Enable service-to-service communication** using Docker's internal networking
## Prerequisites
- Docker Desktop installed and running
- Docker Compose v2.0+ (included with Docker Desktop)
- A `.env` file with required environment variables (see [Configuration](#configuration))
## Quick Start
1. **Clone the repository** and navigate to the project root:
```bash
cd ai.allucanget.biz
```
2. **Configure environment variables** in `.env`:
```bash
# Copy the example if you don't have a .env file
cp .env.example .env
# Edit .env and fill in required values
# - OPENROUTER_API_KEY: Your openrouter.ai API key
# - JWT_SECRET: A random secret for signing JWT tokens
# - FLASK_SECRET_KEY: A random secret for Flask session cookies
```
3. **Build and start the services**:
```bash
docker compose up --build
```
4. **Access the application**:
- Frontend UI: http://localhost:12001
- Backend API: http://localhost:12000
- API Health: http://localhost:12000/health
- Nginx Proxy: http://localhost:80 (routes to frontend) or http://localhost:80/api (routes to backend)
5. **View logs**:
```bash
# All services
docker compose logs -f
# Specific service
docker compose logs -f backend
docker compose logs -f frontend
```
6. **Stop the services**:
```bash
docker compose down
```
## Configuration
### Environment Variables
The `.env` file in the project root is automatically loaded by Docker Compose. Required variables:
| Variable | Purpose | Example |
| -------------------- | ------------------------------------------ | ---------------------------------------------------------------------------- |
| `OPENROUTER_API_KEY` | API key for AI generation | `sk-or-v1-...` |
| `JWT_SECRET` | Secret for JWT token signing | (random hex string) |
| `FLASK_SECRET_KEY` | Secret for Flask session cookies | (random hex string) |
| `BACKEND_URL` | Internal URL for frontend to reach backend | `http://backend:12000` (Docker) or `http://localhost:12000` (local dev) |
| `CORS_ORIGINS` | Allowed CORS origins for backend | `http://localhost:12001` (local) or `https://ai.allucanget.biz` (production) |
| `APP_URL` | Public URL of the backend | `http://localhost` or `https://ai.allucanget.biz` |
| `APP_NAME` | Application name | `AI Allucanget` |
### Volume Mounts
The `docker-compose.yml` defines the following volume:
- `./data:/app/data` — Persists the DuckDB database (`app.db`) between container restarts
## Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Docker Network: app-network (internal bridge) │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────────────┐ │
│ │ Frontend │ │ Backend │ │
│ │ Port 12001 │ │ Port 12000 │ │
│ │ Flask + Gunicorn│◄──►│ FastAPI + Uvicorn │ │
│ │ (Service name: │ │ (Service name: backend) │ │
│ │ frontend) │ │ │ │
│ └──────────────────┘ │ ┌────────────────────┐ │ │
│ ▲ │ │ DuckDB Database │ │ │
│ │ │ │ /app/data/app.db │ │ │
│ ┌────▼──────────────┐ │ └────────────────────┘ │ │
│ │ Nginx (Port 80) │ └──────────────────────────┘ │
│ │ Reverse Proxy │ │
│ └───────────────────┘ │
│ ▲ │
│ │ (bind mount) │
│ Host:80, 443 │
└─────────────────────────────────────────────────────────┘
│
Host OS
```
## Common Tasks
### View service status
```bash
docker compose ps
```
Output example:
```
NAME COMMAND SERVICE STATUS PORTS
ai-backend "uvicorn app.main:a…" backend Up 2m 0.0.0.0:12000->12000/tcp
ai-frontend "gunicorn app.main:…" frontend Up 2m 0.0.0.0:12001->12001/tcp
ai-nginx "nginx -g daemon of…" nginx Up 2m 0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp
```
### Rebuild images
```bash
# Rebuild all services
docker compose build
# Rebuild a specific service
docker compose build backend
docker compose build frontend
```
### Access container shell
```bash
# Backend shell
docker compose exec backend bash
# Frontend shell
docker compose exec frontend bash
```
### View service logs
```bash
# Tail all logs
docker compose logs -f
# Follow only backend logs
docker compose logs -f backend
# Last 100 lines of frontend logs
docker compose logs --tail 100 frontend
```
### Clean up
```bash
# Stop containers but keep volumes and images
docker compose stop
# Stop and remove containers
docker compose down
# Stop containers and remove volumes (WARNING: deletes database!)
docker compose down -v
# Remove images as well
docker compose down --rmi all
```
## Troubleshooting
### "Docker daemon is not running"
**Error**: `error during connect: This error may indicate the client is not properly configured`
**Solution**: Start Docker Desktop (Windows/Mac) or start the Docker daemon (Linux).
### "Port 12000 or 12001 already in use"
**Error**: `Error response from daemon: bind: address already in use`
**Solution**: Either stop the other application using that port, or modify the ports in `docker-compose.yml`:
```yaml
ports:
- "13000:12000" # Maps host:13000 to container:12000
- "13001:12001" # Maps host:13001 to container:12001
```
### Frontend cannot reach backend
**Error**: Connection refused or 502 Bad Gateway
**Ensure**:
1. Backend service is running: `docker compose ps`
2. `BACKEND_URL` in `.env` is set to `http://backend:12000` (not `localhost`)
3. Services are on the same Docker network: `docker compose ps` shows them in the same `docker-compose.yml`
### Database file not persisting
**Issue**: Data is lost after `docker compose down`
**Solution**: The volume mount `./data:/app/data` should persist data automatically. Check that:
1. The `data/` directory exists on your host
2. The volume is mounted correctly in `docker-compose.yml`
3. DuckDB has write permissions to the `data/` directory
## Performance Tips
- **Development**: Use `docker compose up` for real-time logs and quick iterations
- **Background**: Use `docker compose up -d` to run services detached
- **Rebuilds**: Use `docker compose up --build` only when dependencies or Dockerfiles change
- **Caching**: Docker caches layers; unchanged steps build faster
## Next Steps
- **Deployment**: See [Coolify Deployment](./coolify.md) for production deployment
- **Testing**: See [Testing Guide](../TESTING.md) for running tests
- **Architecture**: See [Deployment View](../7-deployment-view.md) for system architecture
## Additional Resources
- [Docker Compose Documentation](https://docs.docker.com/compose/)
- [Docker Networking Guide](https://docs.docker.com/network/)
- [Best Practices for Writing Dockerfiles](https://docs.docker.com/develop/dev-best-practices/dockerfile_best-practices/)