From 8abcea154b43e3859cf0ebe5e058b07a2ee71d19 Mon Sep 17 00:00:00 2001
From: Samir Boulahtit <samir.boulahtit@wizard.lu>
Date: Fri, 13 Feb 2026 00:09:48 +0100
Subject: [PATCH] docs(deployment): expand maintenance section with deploy and
 debug commands

Add one-liner deploy command, log viewing/filtering, container status
checks, and update remaining tasks list.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs/deployment/hetzner-server-setup.md | 78 ++++++++++++++++++++-----
 1 file changed, 65 insertions(+), 13 deletions(-)

diff --git a/docs/deployment/hetzner-server-setup.md b/docs/deployment/hetzner-server-setup.md
index c042c1ad..ecf9aec9 100644
--- a/docs/deployment/hetzner-server-setup.md
+++ b/docs/deployment/hetzner-server-setup.md
@@ -29,14 +29,23 @@ Complete step-by-step guide for deploying Wizamart on a Hetzner Cloud VPS.
     - Caddy 2.10.2 reverse proxy with auto-SSL (Let's Encrypt)
     - Temporary firewall rules removed (ports 3000, 8001)
     - Gitea Actions runner v0.2.13 registered and running as systemd service
+    - SSH key added to Gitea for local push via SSH
+    - Git remote updated: `ssh://git@git.wizard.lu:2222/sboulahtit/orion.git`
+    - CI ruff (lint) job passing
+    - ProxyHeadersMiddleware added for correct HTTPS behind Caddy
+    - Fixed TierLimitExceededException import and Pydantic @field_validator bugs
+    - `wizard.lu` serving frontend with CSS over HTTPS (mixed content fixed)
 
-    **Remaining:**
+    - `/merchants` and `/admin` redirect fix (CMS catch-all was intercepting)
 
-    - [ ] DNS A records for additional platform domains (`oms.lu`, `loyaltyplus.lu`)
+    **Remaining for next session:**
+
+    - [ ] CI pytest job — fails due to pydantic version mismatch (requirements need pinning)
+    - [ ] DNS A records for platform domains (`oms.lu`, `loyaltyplus.lu`)
     - [ ] Uncomment platform domains in Caddyfile after DNS propagation
     - [ ] AAAA (IPv6) records for all domains
     - [ ] Update `platforms` table `domain` column to match production domains
-    - [ ] Verify CI pipeline runs successfully on push
+
 
 ## Installed Software Versions
 
@@ -750,20 +759,15 @@ git stash pop
 
 ## Maintenance
 
-### View logs
+### Deploy updates (pull & rebuild)
+
+After pushing code to Gitea from local:
 
 ```bash
-docker compose --profile full logs -f api
-docker compose --profile full logs -f celery-worker
+cd ~/apps/orion && git pull && docker compose --profile full up -d --build
 ```
 
-### Restart services
-
-```bash
-docker compose --profile full restart api
-```
-
-### Update deployment
+If there are local changes on the server (e.g. `.env` edits), stash first:
 
 ```bash
 cd ~/apps/orion
@@ -771,9 +775,57 @@ git stash          # Save local config changes
 git pull
 git stash pop      # Re-apply local config
 docker compose --profile full up -d --build
+```
+
+If the update includes database migrations:
+
+```bash
 docker compose --profile full exec -e PYTHONPATH=/app api python -m alembic upgrade heads
 ```
 
+### View logs
+
+```bash
+# Follow all logs in real-time
+docker compose --profile full logs -f
+
+# Follow a specific service
+docker compose --profile full logs -f api
+docker compose --profile full logs -f celery-worker
+docker compose --profile full logs -f celery-beat
+docker compose --profile full logs -f flower
+
+# View last N lines (useful for debugging crashes)
+docker compose --profile full logs --tail=50 api
+docker compose --profile full logs --tail=100 celery-worker
+
+# Filter logs for errors
+docker compose --profile full logs api | grep -i "error\|exception\|failed"
+```
+
+### Check container status
+
+```bash
+# Overview of all containers (health, uptime, ports)
+docker compose --profile full ps
+
+# Watch for containers stuck in "Restarting" — indicates a crash loop
+# Healthy containers show: Up Xs (healthy)
+```
+
+### Restart services
+
+```bash
+# Restart a single service
+docker compose --profile full restart api
+
+# Restart everything
+docker compose --profile full restart
+
+# Full rebuild (after code changes)
+docker compose --profile full up -d --build
+```
+
 ### Quick access URLs
 
 After Caddy is configured: