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

Co-authored-by: Copilot <copilot@github.com>
2026-04-28 10:20:58 +02:00
parent 80999b3659
commit 5371bdce3b
11 changed files with 506 additions and 21 deletions
@@ -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.