# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Automates provisioning of customer Proxmox LXC containers running a Docker stack (n8n + PostgreSQL/pgvector + PostgREST) with automatic OPNsense NGINX reverse proxy registration. Intended for a multi-tenant SaaS setup ("BotKonzept") where each customer gets an isolated container.

## Key Commands

```bash
# Create a new customer LXC (must run on Proxmox host)
bash install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90

# With debug output (logs on stderr instead of only to file)
DEBUG=1 bash install.sh --storage local-zfs --bridge vmbr0

# With APT caching proxy
bash install.sh --storage local-zfs --apt-proxy http://192.168.45.2:3142

# Setup the BotKonzept management LXC (fixed CTID 5010)
bash setup_botkonzept_lxc.sh

# Delete an nginx proxy entry in OPNsense
bash delete_nginx_proxy.sh --hostname sb-<unixts>
```

`install.sh` outputs a single JSON line to stdout with all credentials and URLs. Detailed logs go to `logs/<hostname>.log`. Credentials are saved to `credentials/<hostname>.json`.

## Architecture

### Script Dependency Tree

```
install.sh
├── sources libsupabase.sh          (Proxmox helpers, logging, crypto, n8n setup)
├── calls setup_nginx_proxy.sh      (OPNsense API integration)
└── uses lib_installer_json_api.sh  (PostgREST DB storage - optional)

setup_botkonzept_lxc.sh            (Standalone, for management LXC CTID 5010)
```

### Infrastructure Assumptions (hardcoded defaults)

| Service | Address |
|---|---|
| OPNsense Firewall | `192.168.45.1:4444` |
| Apt-Cacher NG | `192.168.45.2:3142` |
| Docker Registry Mirror | `192.168.45.2:5000` |
| Ollama API | `192.168.45.3:11434` |
| Default VLAN | 90 |
| Default storage | `local-zfs` |
| Default base domain | `userman.de` |

### What `install.sh` Does (Steps 5–11)

1. **Step 5**: Creates and starts Proxmox LXC (Debian 12), waits for DHCP IP
2. **Step 6**: Installs Docker CE + Compose plugin inside the CT
3. **Step 7**: Generates secrets (PG password, JWT, n8n encryption key), writes `.env` and `docker-compose.yml` into CT, starts the stack
4. **Step 8**: Creates n8n owner account via REST API
5. **Step 10**: Imports and activates the RAG workflow via n8n API, sets up credentials (Postgres + Ollama)
6. **Step 10a**: Installs a systemd service (`n8n-workflow-reload.service`) that re-imports and re-activates the workflow on every LXC restart
7. **Step 11**: Registers an NGINX upstream/location in OPNsense via its REST API

### Docker Stack Inside Each LXC (`/opt/customer-stack/`)

- `postgres` – pgvector/pgvector:pg16, initialized from `sql/` directory
- `postgrest` – PostgREST, exposes Supabase-compatible REST API on port 3000 (mapped to `POSTGREST_PORT`)
- `n8n` – n8n automation, port 5678

All three share a `customer-net` bridge network. The n8n instance connects to PostgREST via the Docker internal hostname `postgrest:3000` (not the external IP).

### Key Files

| File | Purpose |
|---|---|
| `libsupabase.sh` | Core library: logging (`info`/`warn`/`die`), Proxmox helpers (`pct_exec`, `pct_push_text`, `pve_*`), crypto (`gen_password_policy`, `gen_hex_64`), n8n setup (`n8n_setup_rag_workflow`) |
| `setup_nginx_proxy.sh` | OPNsense API client; registers upstream + location for new CT |
| `lib_installer_json_api.sh` | Stores installer JSON output into the BotKonzept Postgres DB via PostgREST |
| `sql/botkonzept_schema.sql` | Customer management schema (customers, instances, emails, payments) for the BotKonzept management LXC |
| `sql/init_pgvector.sql` | Inline in `install.sh`; creates pgvector extension, `documents` table, `match_documents` function, PostgREST roles |
| `templates/reload-workflow.sh` | Runs inside customer LXC on every restart; logs to `/opt/customer-stack/logs/workflow-reload.log` |
| `RAGKI-BotPGVector.json` | Default n8n workflow template (RAG KI-Bot with PGVector) |

### Output and Logging

- **Normal mode** (`DEBUG=0`): all script output goes to `logs/<hostname>.log`; only the final JSON is printed to stdout (via fd 3)
- **Debug mode** (`DEBUG=1`): logs also written to stderr; JSON is formatted with `python3 -m json.tool`
- Each customer container hostname is `sb-<unix_timestamp>`; CTID = unix_timestamp − 1,000,000,000

### n8n Password Policy

Passwords must be 8+ characters with at least 1 uppercase and 1 number. Enforced by `password_policy_check` in `libsupabase.sh`. Auto-generated passwords use `gen_password_policy`.

### Workflow Auto-Reload

On LXC restart, `n8n-workflow-reload.service` runs `reload-workflow.sh`, which:
1. Waits for n8n API to be ready (up to 60s)
2. Logs in with owner credentials from `.env`
3. Deletes the existing "RAG KI-Bot (PGVector)" workflow
4. Looks up existing Postgres and Ollama credential IDs
5. Processes the workflow template (replaces credential IDs using Python)
6. Imports and activates the new workflow