Document Portainer deployment

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: