From 4d6d9b53d3a8d0f5e441d1f9ae6eda8b3d5716d2 Mon Sep 17 00:00:00 2001
From: masterdev <masterdev@users.noreply.local>
Date: Tue, 16 Jun 2026 22:14:42 +0100
Subject: [PATCH] Document Portainer deployment

---
 README.md          | 108 +++++++++++++++++++++++++++++++++++++++++++++
 docker-compose.yml |  18 ++++----
 2 files changed, 116 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 34dfd40..a9ee229 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,114 @@ Exposed services:
 - PostgreSQL: `localhost:5432`
 - MQTT: `localhost:1883`
 
+## Deploy With Portainer
+
+Use a Portainer `Stack` from the Git repository. Do not paste only the Compose
+file into the web editor, because the stack also needs these repository files:
+
+- `database/init.sql`
+- `database/seed.sql`
+- `mqtt/mosquitto.conf`
+- `backend/`
+- `frontend/`
+- `edge-simulator/`
+
+### 1. Create The Stack
+
+In Portainer:
+
+1. Go to `Stacks`.
+2. Click `Add stack`.
+3. Choose `Repository`.
+4. Set repository URL:
+
+```text
+https://gitea.b2i.business/masterdev/plast-track.git
+```
+
+5. Set branch:
+
+```text
+main
+```
+
+6. Set Compose path:
+
+```text
+docker-compose.yml
+```
+
+### 2. Configure Stack Variables
+
+For a local server accessed directly by IP, replace `SERVER_IP` with the host IP:
+
+```env
+POSTGRES_DB=plasttrack
+POSTGRES_USER=plasttrack
+POSTGRES_PASSWORD=change-this-password
+FRONTEND_ORIGIN=http://SERVER_IP:5173
+VITE_API_BASE_URL=http://SERVER_IP:8000
+VITE_WS_URL=ws://SERVER_IP:8000/ws/dashboard
+```
+
+For a domain with HTTPS and a reverse proxy, use:
+
+```env
+POSTGRES_DB=plasttrack
+POSTGRES_USER=plasttrack
+POSTGRES_PASSWORD=change-this-password
+FRONTEND_ORIGIN=https://plasttrack.example.com
+VITE_API_BASE_URL=https://api.plasttrack.example.com
+VITE_WS_URL=wss://api.plasttrack.example.com/ws/dashboard
+```
+
+Important: do not keep `localhost` in `VITE_API_BASE_URL` or `VITE_WS_URL`
+for a remote deployment. `localhost` would point to the operator's browser
+machine, not the Docker host.
+
+### 3. Deploy
+
+Click `Deploy the stack`.
+
+Expected exposed ports:
+
+- frontend: `5173`
+- backend API: `8000`
+- MQTT: `1883`
+- MQTT WebSocket listener: `9001`
+
+PostgreSQL is intentionally not exposed by default in the Compose file. It is
+only reachable by the backend on the internal Docker network.
+
+### 4. Verify
+
+Open:
+
+```text
+http://SERVER_IP:5173
+```
+
+Check the backend:
+
+```text
+http://SERVER_IP:8000/health
+```
+
+Expected response:
+
+```json
+{"status":"ok"}
+```
+
+### 5. Updating From Gitea
+
+After pushing new commits to Gitea:
+
+1. Open the stack in Portainer.
+2. Click `Pull and redeploy` or `Update the stack`.
+3. Enable rebuild if Portainer asks, because `backend`, `frontend`, and
+   `edge-simulator` are built from the repository.
+
 ## Demo Data
 
 Seeded machines:
diff --git a/docker-compose.yml b/docker-compose.yml
index 923204e..2c32ec1 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -2,17 +2,15 @@ services:
   database:
     image: postgres:16-alpine
     environment:
-      POSTGRES_DB: plasttrack
-      POSTGRES_USER: plasttrack
-      POSTGRES_PASSWORD: plasttrack
-    ports:
-      - "5432:5432"
+      POSTGRES_DB: ${POSTGRES_DB:-plasttrack}
+      POSTGRES_USER: ${POSTGRES_USER:-plasttrack}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-plasttrack}
     volumes:
       - postgres_data:/var/lib/postgresql/data
       - ./database/init.sql:/docker-entrypoint-initdb.d/01-init.sql:ro
       - ./database/seed.sql:/docker-entrypoint-initdb.d/02-seed.sql:ro
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U plasttrack -d plasttrack"]
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
       interval: 5s
       timeout: 3s
       retries: 20
@@ -34,11 +32,11 @@ services:
     build:
       context: ./backend
     environment:
-      DATABASE_URL: postgresql+psycopg://plasttrack:plasttrack@database:5432/plasttrack
+      DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-plasttrack}:${POSTGRES_PASSWORD:-plasttrack}@database:5432/${POSTGRES_DB:-plasttrack}
       MQTT_HOST: mqtt
       MQTT_PORT: 1883
       MQTT_TOPIC: plasttrack/machines/+/events
-      FRONTEND_ORIGIN: http://localhost:5173
+      FRONTEND_ORIGIN: ${FRONTEND_ORIGIN:-http://localhost:5173}
     depends_on:
       database:
         condition: service_healthy
@@ -63,8 +61,8 @@ services:
     build:
       context: ./frontend
     environment:
-      VITE_API_BASE_URL: http://localhost:8000
-      VITE_WS_URL: ws://localhost:8000/ws/dashboard
+      VITE_API_BASE_URL: ${VITE_API_BASE_URL:-http://localhost:8000}
+      VITE_WS_URL: ${VITE_WS_URL:-ws://localhost:8000/ws/dashboard}
     depends_on:
       - backend
     ports: