From ab18bff6b60bb2aa1af660d3fa967733731731ae Mon Sep 17 00:00:00 2001
From: Damien Arnodo <damien@noreply.localhost>
Date: Thu, 5 Feb 2026 09:21:18 +0000
Subject: [PATCH] docs: comprehensive README for Infrahub deployment

---
 README.md | 120 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 118 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 076ef7a..db4a26f 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,119 @@
-# infrahub-deployment
+# Infrahub Deployment
 
-GitOps deployment for Infrahub infrastructure data management platform with Tailscale HTTPS access via Komodo
\ No newline at end of file
+GitOps deployment for Infrahub infrastructure data management platform with Tailscale HTTPS access via Komodo.
+
+## Prerequisites
+
+### Generate Secrets
+
+```bash
+# Generate admin token and secret key (UUID format)
+uuidgen  # Example: 06438eb2-8019-4776-878c-0941b1f1d1ec
+uuidgen  # Example: 327f747f-efac-42be-9e73-999f08f86b92
+```
+
+### Tailscale Auth Key
+
+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**: `infrahub`
+   - **Server**: Select your target server
+   - **Source**: Git Repo
+   - **Git Provider**: `gitea.arnodo.fr` (or your provider)
+   - **Repo**: `Damien/infrahub-deployment`
+   - **Branch**: `main`
+   - **File Paths**: `docker-compose.yml`
+
+### 3. Configure Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `TS_AUTHKEY` | Tailscale auth key (reusable) | `tskey-auth-xxx` |
+| `VERSION` | Infrahub version (optional) | `latest` or `1.5.0` |
+| `NEO4J_PASSWORD` | Neo4j database password | *secret* |
+| `RABBITMQ_USER` | RabbitMQ username | `infrahub` |
+| `RABBITMQ_PASSWORD` | RabbitMQ password | *secret* |
+| `INFRAHUB_ADMIN_TOKEN` | Initial admin API token | `06438eb2-...` |
+| `INFRAHUB_SECRET_KEY` | Security secret key | `327f747f-...` |
+| `INFRAHUB_ALLOW_ANONYMOUS` | Allow anonymous access | `false` |
+| `INFRAHUB_LOG_LEVEL` | Log level | `INFO` |
+
+> **Tip**: Use Komodo's secret variables (marked with 🔒) for sensitive values.
+
+### 4. Deploy
+
+Click **Deploy** in Komodo.
+
+## 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
+
+Once deployed: https://infrahub.taila5ad8.ts.net
+
+Default credentials:
+- Username: `admin`
+- Password: `infrahub`
+
+> **Important**: Change the default password after first login!
+
+## Services
+
+| Service | Description | Image |
+|---------|-------------|-------|
+| `tailscale` | HTTPS ingress via Tailscale | `tailscale/tailscale` |
+| `database` | Neo4j graph database | `neo4j:5.23-community` |
+| `cache` | Redis cache | `redis:7-alpine` |
+| `message-queue` | RabbitMQ message broker | `rabbitmq:3-management-alpine` |
+| `infrahub-server` | API + UI | `registry.opsmill.io/opsmill/infrahub` |
+| `task-worker` | Background task worker | `registry.opsmill.io/opsmill/infrahub` |
+
+## Upgrading
+
+1. Update the `VERSION` environment variable in Komodo
+2. Redeploy the stack
+
+After upgrading, run the database migrations:
+```bash
+docker exec -it infrahub-server infrahub db migrate
+docker exec -it infrahub-server infrahub db update-core-schema
+```
+
+## Backup
+
+### Neo4j Database
+
+```bash
+docker exec -it infrahub-database neo4j-admin database backup --to-path=/backups neo4j
+docker cp infrahub-database:/backups/neo4j-<timestamp>.backup ./
+```
+
+## Repository Structure
+
+```
+infrahub-deployment/
+├── docker-compose.yml       # Stack definition (relative paths)
+├── serve-config.json        # Tailscale HTTPS serve config
+└── README.md
+```
+
+## References
+
+- [Infrahub Documentation](https://docs.infrahub.app/)
+- [Infrahub GitHub](https://github.com/opsmill/infrahub)