feat: migrate to traefik and redis for scaling and update docs

Author: matteosusca

DEPLOYMENT.md

@@ -20,46 +20,38 @@ Access:
 JWT_SECRET=your-secret-here docker compose -f docker-compose.prod.yml up -d --build
 ```
 
-Access everything through the client port:
+Access everything through the entry point port:
 - **App**: http://localhost:3080
 - **API**: http://localhost:3080/api
 - **Swagger**: http://localhost:3080/api-docs
 - **Mongo Express**: http://localhost:8081
 
-The client's nginx proxies API/Socket requests internally.
+Traefik handles routing and sticky sessions for Socket.io.
 
 ### Environment Variables
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `JWT_SECRET` | **Yes** | - | Secret for JWT tokens |
 | `CLIENT_ORIGIN` | No | `*` | CORS origins (comma-separated for multiple) |
-| `CLIENT_PORT` | No | `3080` | Host port for frontend |
+| `CLIENT_PORT` | No | `3080` | Host port for frontend/entry point |
+| `REDIS_URL` | No | `redis://redis:6379` | Internal Redis URL |
+| `CANVAS_WIDTH` | No | `64` | Default canvas width |
+| `CANVAS_HEIGHT` | No | `64` | Default canvas height |
 | `ME_PORT` | No | `8081` | Host port for Mongo Express |
 | `ME_USERNAME` | No | `admin` | Mongo Express username |
 | `ME_PASSWORD` | No | `changeme` | Mongo Express password |
-| `VITE_API_URL` | No | `` | API URL (only if exposing API on separate domain) |
+| `VITE_API_URL` | No | `` | API URL (used at build time for client) |
 
-### Portainer + Nginx Proxy Manager
+### Portainer + Reverse Proxy
 
-The client's nginx proxies API/Socket internally, so you only need to expose the app itself.
+Traefik handles internal routing, so you only need to expose the Traefik entry point.
 
 **Minimal setup (recommended):**
 
 | Domain | Forward To | Port | WebSocket |
 |--------|------------|------|-----------|
-| `app.example.com` | `pixie-client` | 3080 | **Yes** |
-
-That's it. API, Swagger, and Socket.io are all proxied through the client.
-
-**Optional: Expose additional services**
-
-If you want direct access to other services (NPM must be on the same Docker network, or add port mappings to compose):
-
-| Domain | Forward To | Port | WebSocket |
-|--------|------------|------|-----------|
-| `api.example.com` | `pixie-server` | 3000 | **Yes** |
-| `mongo.example.com` | `pixie-mongo-express` | 8081 | No |
+| `app.example.com` | `pixie-traefik` | 80 | **Yes** |
 
 **Steps:**
 
@@ -71,41 +63,21 @@ If you want direct access to other services (NPM must be on the same Docker netw
      CLIENT_ORIGIN=https://app.example.com
      ME_PASSWORD=secure-password
      ```
-   - If exposing API separately, add it to CORS: `CLIENT_ORIGIN=https://app.example.com,https://api.example.com`
-
-2. **Create NPM Proxy Host**
-   - Domain: `app.example.com`
-   - Forward: `pixie-client` port `3080`
-   - Enable **Websockets Support**
-   - Add SSL via Let's Encrypt
 
-3. **SSL**: Use NPM's built-in Let's Encrypt for HTTPS.
-
-### CORS Configuration
-
-`CLIENT_ORIGIN` supports:
-- Single origin: `https://app.example.com`
-- Multiple origins: `https://app.example.com,https://api.example.com`
-- Allow all: `*` (not recommended for production)
-
-Include both your app domain and API domain if Swagger needs to make requests.
+2. **Reverse Proxy (Nginx Proxy Manager / Caddy)**
+   - Point your domain to the Docker host.
+   - Forward traffic to the Docker host on port `3080` (or your configured `CLIENT_PORT`), or directly to the `pixie-traefik` container on port `80` if the proxy is on the same Docker network.
+   - Enable **Websockets Support**.
 
 ### Architecture
 
-**Standalone** (single entry point):
-```
-localhost:3080 ──► pixie-client (nginx)
-                      ├── /           → static files
-                      ├── /api/       → proxy to pixie-server:3000
-                      ├── /api-docs   → proxy to pixie-server:3000
-                      └── /socket.io/ → proxy to pixie-server:3000 (WebSocket)
-```
-
-**With NPM** (separate domains):
+**Standalone** (Traefik as entry point):
 ```
-app.example.com ──► NPM ──► pixie-client:3080
-api.example.com ──► NPM ──► pixie-server:3000 (enable WebSocket)
-mongo.example.com ──► NPM ──► pixie-mongo-express:8081
+localhost:3080 ──► pixie-traefik
+                      ├── /           → pixie-client:80
+                      ├── /api/       → pixie-server:3000
+                      ├── /api-docs   → pixie-server:3000
+                      └── /socket.io/ → pixie-server:3000 (WebSocket + Sticky Sessions)
 ```
 
-MongoDB is **not exposed** externally—only accessible within the Docker network.
+MongoDB and Redis are **not exposed** externally—only accessible within the Docker network.

README.md

@@ -33,21 +33,31 @@ docker compose up -d --scale server=3
 
 | Service | URL |
 |---------|-----|
-| App | http://localhost:5173 |
-| API Docs | http://localhost:3000/api-docs |
+| App | http://localhost:3080 |
+| API Docs | http://localhost:3080/api-docs |
 
-> 💡 **Dynamic Scaling:** You can add more server instances at any time using `--scale server=N`. Nginx is configured with `least_conn` to balance active connections across all instances.
+> 💡 **Dynamic Scaling:** You can add more server instances at any time using `--scale server=N`. Traefik is configured with `least_conn` and sticky sessions to balance active connections across all instances.
 
 ### Manual
 
 ```bash
+# Prerequisites: MongoDB and Redis running locally
+
 # Server
 cd server && npm install && npm run dev
 
 # Client (separate terminal)
 cd client && npm install && npm run dev
 ```
 
+### Testing
+
+Run the full test suite (requires Docker):
+```bash
+npm test
+```
+This script handles temporary infrastructure (Redis) automatically.
+
 ### Production
 
 ```bash
@@ -64,14 +74,15 @@ JWT_SECRET=your-secret docker compose -f docker-compose.prod.yml up -d --build
 |----------|---------|-------------|
 | `JWT_SECRET` | `dev-secret-key` | **Required in production** |
 | `MONGO_URI` | `mongodb://localhost:27017/pixie` | Database connection |
+| `REDIS_URL` | `redis://localhost:6379` | Redis connection for scaling |
 | `PORT` | `3000` | Server port |
 
 ---
 
 ## 🛠️ Built With
 
 **Frontend:** Vue.js 3 • Pinia • Vite • Socket.IO  
-**Backend:** Node.js • Express • MongoDB • Socket.IO
+**Backend:** Node.js • Express • MongoDB • Redis • Socket.IO
 
 ---
 

client/nginx.conf

@@ -30,32 +30,5 @@ http {
             index index.html index.htm;
             try_files $uri $uri/ /index.html;
         }
-
-        # Proxy API requests to the backend
-        location /api/ {
-            proxy_pass http://pixie-server:3000;
-            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;
-        }
-
-        # Proxy Swagger UI
-        location /api-docs {
-            proxy_pass http://pixie-server:3000/api-docs;
-            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;
-        }
-
-        # Proxy Socket.io (WebSocket)
-        location /socket.io/ {
-            proxy_pass http://pixie-server:3000;
-            proxy_http_version 1.1;
-            proxy_set_header Upgrade $http_upgrade;
-            proxy_set_header Connection "upgrade";
-            proxy_set_header Host $host;
-        }
     }
 }

docker-compose.prod.yml

@@ -2,7 +2,7 @@
 #
 # Usage: JWT_SECRET=your-secret docker compose -f docker-compose.prod.yml up -d --build
 #
-# Access: http://localhost:3080 (app + API + Swagger via nginx proxy)
+# Access: http://localhost:3080 (app + API + Swagger via Traefik proxy)
 #
 # For Portainer + NPM: proxy app.example.com -> pixie-client:3080 (enable WebSocket)
 #
@@ -34,21 +34,36 @@ services:
     networks:
       - pixie-net
 
+  redis:
+    image: redis:7-alpine
+    container_name: pixie-redis
+    restart: unless-stopped
+    networks:
+      - pixie-net
+
   server:
     build:
       context: ./server
       target: production-stage
     image: pixie-server:latest
-    container_name: pixie-server
     restart: unless-stopped
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.server.rule=PathPrefix(`/api`) || PathPrefix(`/socket.io`) || PathPrefix(`/api-docs`)"
+      - "traefik.http.services.server.loadbalancer.server.port=3000"
+      - "traefik.http.services.server.loadbalancer.strategy=p2c"
+      - "traefik.http.services.server.loadbalancer.sticky.cookie=true"
+      - "traefik.http.services.server.loadbalancer.sticky.cookie.name=PIXIE_SESSION"
     environment:
       PORT: 3000
       MONGO_URI: mongodb://mongo:27017/pixie
+      REDIS_URL: redis://redis:6379
       CLIENT_ORIGIN: ${CLIENT_ORIGIN:-*}
       JWT_SECRET: ${JWT_SECRET:?JWT_SECRET is required}
       NODE_ENV: production
     depends_on:
       - mongo
+      - redis
     networks:
       - pixie-net
 
@@ -59,10 +74,27 @@ services:
       args:
         VITE_API_URL: ${VITE_API_URL:-}
     image: pixie-client:latest
-    container_name: pixie-client
     restart: unless-stopped
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.client.rule=PathPrefix(`/`)"
+      - "traefik.http.services.client.loadbalancer.server.port=80"
+    networks:
+      - pixie-net
+
+  traefik:
+    image: traefik:latest
+    container_name: pixie-traefik
+    restart: unless-stopped
+    command:
+      - "--providers.docker=true"
+      - "--providers.docker.endpoint=unix:///var/run/docker.sock"
+      - "--providers.docker.exposedbydefault=false"
+      - "--entrypoints.web.address=:80"
     ports:
       - "${CLIENT_PORT:-3080}:80"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
     networks:
       - pixie-net
 

docker-compose.yml

@@ -35,8 +35,13 @@ services:
       context: ./server
       target: dev-stage
     image: pixie-server:dev
-    deploy:
-      endpoint_mode: dnsrr
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.server.rule=PathPrefix(`/api`) || PathPrefix(`/socket.io`) || PathPrefix(`/api-docs`)"
+      - "traefik.http.services.server.loadbalancer.server.port=3000"
+      - "traefik.http.services.server.loadbalancer.strategy=p2c"
+      - "traefik.http.services.server.loadbalancer.sticky.cookie=true"
+      - "traefik.http.services.server.loadbalancer.sticky.cookie.name=PIXIE_SESSION"
     environment:
       PORT: 3000
       MONGO_URI: mongodb://mongo:27017/pixie
@@ -53,15 +58,20 @@ services:
       - pixie-net
     command: npm run dev
 
-  nginx:
-    image: nginx:alpine
-    container_name: pixie-nginx
+  traefik:
+    image: traefik:latest
+    container_name: pixie-traefik
+    command:
+      - "--api.insecure=true"
+      - "--providers.docker=true"
+      - "--providers.docker.endpoint=unix:///var/run/docker.sock"
+      - "--providers.docker.exposedbydefault=false"
+      - "--entrypoints.web.address=:3000"
     ports:
-      - "3000:80"
+      - "3000:3000"
+      - "8080:8080"
     volumes:
-      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
-    depends_on:
-      - server
+      - /var/run/docker.sock:/var/run/docker.sock:ro
     networks:
       - pixie-net
 
@@ -78,7 +88,7 @@ services:
       - ./client/src:/app/src
       - ./client/index.html:/app/index.html
     depends_on:
-      - nginx
+      - traefik
     networks:
       - pixie-net
     command: npm run dev -- --host