From 99611f7c7e1411cec4955e2eeb60992c676590c7 Mon Sep 17 00:00:00 2001
From: Damien Arnodo <damien@noreply.localhost>
Date: Sat, 31 Jan 2026 12:11:59 +0000
Subject: [PATCH] docs: update README for Komodo deployment

---
 README.md | 101 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 77 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index e220f98..0a35fb1 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Prefect Deployment
 
-GitOps deployment for Prefect workflow orchestration with Tailscale HTTPS access.
+GitOps deployment for Prefect workflow orchestration with Tailscale HTTPS access via Komodo.
 
 ## Prerequisites
 
@@ -18,30 +18,56 @@ GRANT ALL PRIVILEGES ON DATABASE prefect TO prefect;
 GRANT ALL ON SCHEMA public TO prefect;
 ```
 
-### Host Configuration
-
-Download configuration files to `/opt/prefect` (first time only):
-
-```bash
-sudo mkdir -p /opt/prefect/tailscale
-sudo curl -o /opt/prefect/tailscale/serve-config.json https://gitea.arnodo.fr/Damien/prefect-deployment/raw/branch/main/serve-config.json
-```
-
 ### Tailscale Auth Key
 
 Generate a reusable auth key from https://login.tailscale.com/admin/settings/keys
 
-## Deployment
+## Deployment with Komodo
 
-1. Create a new stack in Portainer
-2. Select "Repository" and point to this repository
-3. Portainer will load `stack.env` automatically
-4. Override sensitive values (`CHANGE_ME`) in the environment variables section:
-   - `TS_AUTHKEY` - Tailscale auth key (reusable recommended)
-   - `DB_PASSWORD` - PostgreSQL password
-   - `S3_ACCESS_KEY` - Garage S3 access key
-   - `S3_SECRET_KEY` - Garage S3 secret key
-5. Deploy
+### 1. Add Git Provider (if using private repo)
+
+In Komodo UI: Settings → Git Providers → Add your Gitea instance credentials.
+
+### 2. Create Stack
+
+1. Navigate to **Stacks** → **New Stack**
+2. Configure:
+   - **Name**: `prefect`
+   - **Server**: Select your target server
+   - **Source**: Git Repo
+   - **Git Provider**: `gitea.arnodo.fr` (or your provider)
+   - **Repo**: `Damien/prefect-deployment`
+   - **Branch**: `main`
+
+### 3. Configure Environment Variables
+
+In the stack configuration, add the following environment variables:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `TS_AUTHKEY` | Tailscale auth key (reusable) | `tskey-auth-xxx` |
+| `DB_HOST` | PostgreSQL host | `postgresql.taila5ad8.ts.net` |
+| `DB_PORT` | PostgreSQL port | `5432` |
+| `DB_USER` | Database user | `prefect` |
+| `DB_PASSWORD` | Database password | *secret* |
+| `S3_ACCESS_KEY` | Garage S3 access key | *secret* |
+| `S3_SECRET_KEY` | Garage S3 secret key | *secret* |
+| `S3_ENDPOINT_URL` | Garage S3 endpoint | `https://s3.taila5ad8.ts.net` |
+
+> **Tip**: Use Komodo's secret variables (marked with 🔒) for sensitive values.
+
+### 4. Deploy
+
+Click **Deploy** in Komodo. The stack will clone the repository and start all services.
+
+## GitOps Workflow
+
+### Auto-deploy on Git Push
+
+1. In Komodo, go to your stack settings
+2. Enable **Auto Deploy** on push
+3. Copy the webhook URL
+4. Add it to your Gitea repository: Settings → Webhooks
 
 ## Access
 
@@ -76,10 +102,37 @@ my_backup_flow.deploy(
 )
 ```
 
-## Directory Structure
+## Architecture
 
 ```
-/opt/prefect/
-└── tailscale/
-    └── serve-config.json     # Tailscale HTTPS configuration
+┌─────────────────────────────────────────────────────────────┐
+│                     Tailscale Network                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌─────────────┐     ┌─────────────┐     ┌──────────────┐  │
+│  │  Tailscale  │────▶│   Prefect   │────▶│  PostgreSQL  │  │
+│  │   Sidecar   │     │   Server    │     │  (external)  │  │
+│  │   :443      │     │   :4200     │     │              │  │
+│  └─────────────┘     └──────┬──────┘     └──────────────┘  │
+│                             │                               │
+│                      ┌──────▼──────┐                       │
+│                      │    Redis    │                       │
+│                      │ (messaging) │                       │
+│                      └─────────────┘                       │
+│                                                             │
+│  ┌─────────────────┐     ┌─────────────────┐               │
+│  │ Prefect Services│     │  Backup Worker  │──▶ Garage S3  │
+│  │  (background)   │     │ (pg-backup-pool)│               │
+│  └─────────────────┘     └─────────────────┘               │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Repository Structure
+
+```
+prefect-deployment/
+├── docker-compose.yml     # Stack definition (relative paths)
+├── serve-config.json      # Tailscale HTTPS serve config
+└── README.md
 ```