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

---
 README.md | 138 ++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 109 insertions(+), 29 deletions(-)

diff --git a/README.md b/README.md
index f9be6f6..fc823a0 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Netbox Deployment
 
-GitOps deployment for Netbox with Tailscale HTTPS access.
+GitOps deployment for Netbox with Tailscale HTTPS access via Komodo.
 
 ## Prerequisites
 
@@ -17,50 +17,130 @@ ALTER DATABASE netbox OWNER TO netbox;
 GRANT CREATE ON DATABASE netbox TO netbox;
 ```
 
-### Host Configuration
-
-Download configuration files to `/opt/netbox` (first time only):
-
-```bash
-sudo mkdir -p /opt/netbox/{tailscale,app}
-sudo curl -o /opt/netbox/tailscale/serve-config.json https://gitea.arnodo.fr/Damien/netbox-deployment/raw/branch/main/serve-config.json
-sudo curl -o /opt/netbox/app/configuration.py https://gitea.arnodo.fr/Damien/netbox-deployment/raw/branch/main/configuration.py
-sudo curl -o /opt/netbox/app/plugins.py https://gitea.arnodo.fr/Damien/netbox-deployment/raw/branch/main/plugins.py
-```
-
 ### Generate Secret Key
 
 ```bash
 python3 -c "import secrets; print(secrets.token_urlsafe(50))"
 ```
 
-## Deployment
+### Tailscale Auth Key
 
-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
-   - `SECRET_KEY` - Django secret key
-   - `SUPERUSER_PASSWORD` - Initial admin password
-5. Deploy
+Generate a reusable auth key from https://login.tailscale.com/admin/settings/keys
+
+## Deployment with Komodo
+
+### 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**: `netbox`
+   - **Server**: Select your target server
+   - **Source**: Git Repo
+   - **Git Provider**: `gitea.arnodo.fr` (or your provider)
+   - **Repo**: `Damien/netbox-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_NAME` | Database name | `netbox` |
+| `DB_USER` | Database user | `netbox` |
+| `DB_PASSWORD` | Database password | *secret* |
+| `SECRET_KEY` | Django secret key | *generated* |
+| `SUPERUSER_NAME` | Initial admin username | `admin` |
+| `SUPERUSER_EMAIL` | Initial admin email | `admin@example.com` |
+| `SUPERUSER_PASSWORD` | Initial admin password | *secret* |
+| `SKIP_SUPERUSER` | Skip superuser creation | `false` |
+
+> **Tip**: Use Komodo's secret variables (marked with 🔒) for sensitive values like passwords and keys.
+
+### 4. Deploy
+
+Click **Deploy** in Komodo. The stack will:
+1. Clone this repository
+2. Pull container images
+3. Start all services with the configuration files from the repo
 
 ### After First Deployment
 
 Set `SKIP_SUPERUSER=true` to prevent superuser recreation on redeploy.
 
+## 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
+
+Any push to the `main` branch will automatically redeploy the stack.
+
+### Updating Configuration
+
+Simply edit `configuration.py`, `plugins.py`, or `serve-config.json` in the repo and push. Komodo will detect the changes and redeploy if auto-deploy is enabled.
+
 ## Access
 
 Once deployed: https://netbox.taila5ad8.ts.net
 
-## Directory Structure
+## Architecture
 
 ```
-/opt/netbox/
-├── tailscale/
-│   └── serve-config.json    # Tailscale HTTPS configuration
-└── app/
-    ├── configuration.py     # Full NetBox config with DynamicSchemaDict
-    └── plugins.py           # Plugins activation
+┌─────────────────────────────────────────────────────────────┐
+│                     Tailscale Network                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌─────────────┐     ┌─────────────┐     ┌──────────────┐  │
+│  │  Tailscale  │────▶│   NetBox    │────▶│  PostgreSQL  │  │
+│  │   Sidecar   │     │   Server    │     │  (external)  │  │
+│  │   :443      │     │   :8080     │     │              │  │
+│  └─────────────┘     └──────┬──────┘     └──────────────┘  │
+│                             │                               │
+│                      ┌──────▼──────┐                       │
+│                      │    Redis    │                       │
+│                      │  (caching)  │                       │
+│                      └─────────────┘                       │
+│                                                             │
+│  ┌─────────────────┐     ┌─────────────────┐               │
+│  │  NetBox Worker  │     │   Housekeeping  │               │
+│  │  (background)   │     │   (scheduled)   │               │
+│  └─────────────────┘     └─────────────────┘               │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
 ```
+
+## Repository Structure
+
+```
+netbox-deployment/
+├── docker-compose.yml     # Stack definition (relative paths)
+├── configuration.py       # NetBox configuration
+├── plugins.py             # Plugins activation
+├── serve-config.json      # Tailscale HTTPS serve config
+└── README.md
+```
+
+## Troubleshooting
+
+### View Logs in Komodo
+
+Click on the stack → select a service → **Logs** tab.
+
+### Manual Redeploy
+
+If auto-deploy doesn't trigger, click **Pull** then **Deploy** in Komodo.
+
+### Check Service Health
+
+All services show their status in the Komodo UI. Redis includes a healthcheck that must pass before NetBox starts.