From a1a9fc703e529509c61fee3d20797e74d52ff913 Mon Sep 17 00:00:00 2001 From: Eliel Sousa Date: Wed, 7 Oct 2026 20:46:15 -0300 Subject: [PATCH] docs(deployment): adiciona guia de deploy docker, headroom e acesso remoto --- README.md | 2 +- docker-compose.example.yml | 21 +++ docs/wiki/Docker-Deployment.md | 283 +++++++++++++++++++++++++++++++++ docs/wiki/Home.md | 1 + docs/wiki/Installation.md | 1 + docs/wiki/_Sidebar.md | 1 + tools/valida_docs.py | 2 +- 7 files changed, 309 insertions(+), 2 deletions(-) create mode 100644 docs/wiki/Docker-Deployment.md diff --git a/README.md b/README.md index f1f5560..27dd9d7 100644 --- a/README.md +++ b/README.md @@ -123,7 +123,7 @@ side of the mapping in the compose file — the right-hand side is the internal port, the one the process listens on. -Official multi-architecture Docker images (`linux/amd64` and `linux/arm64`) are published automatically to the GitHub Container Registry (GHCR) on pushes to `master` with changes in `src/`. An automated retention policy maintains strictly the last 3 versions: +Official multi-architecture Docker images (`linux/amd64` and `linux/arm64`) are published automatically to the GitHub Container Registry (GHCR) on pushes to `master` and version tags (`v*.*.*`). An automated retention policy maintains strictly the last 3 versions. For a complete deployment guide covering Docker run, Compose, Headroom, Caveman, Cloudflare Tunnel, and Tailscale, see [Docker Deployment Guide](docs/wiki/Docker-Deployment.md). ```bash docker pull ghcr.io/pathbit/ominirtksync:latest diff --git a/docker-compose.example.yml b/docker-compose.example.yml index 7ac13b7..90ad5f0 100644 --- a/docker-compose.example.yml +++ b/docker-compose.example.yml @@ -188,6 +188,27 @@ services: networks: - ominirtksync-net + # --- Otimizacao de tokens (opcional) -------------------------------------- + # + # Comprime payloads de contexto e reduz custos de tokens para agentes de IA (Claude + # Code, Cursor, Windsurf) intermediando chamadas antes do gateway: + # docker compose --profile headroom up -d + ominirtk-headroom: + image: ghcr.io/headroomlabs-ai/headroom:latest + container_name: ominirtk-headroom + hostname: ominirtk-headroom + profiles: ["headroom"] + restart: unless-stopped + ports: + - "127.0.0.1:8787:8787" + environment: + - UPSTREAM_URL=http://ominirtk-router:20128 + - PORT=8787 + networks: + - ominirtksync-net + depends_on: + - ominirtk-router + volumes: ominirtk_tailnet: omniroute_data: diff --git a/docs/wiki/Docker-Deployment.md b/docs/wiki/Docker-Deployment.md new file mode 100644 index 0000000..db6898d --- /dev/null +++ b/docs/wiki/Docker-Deployment.md @@ -0,0 +1,283 @@ +# Docker & Docker Compose Deployment Guide + +*(Versão em português disponível na segunda metade desta página.)* + +Complete guide to deploying **OminiRTkSync** and **OmniRoute** via Docker and Docker Compose, including token optimization with **Headroom** and **Caveman**, remote access via **Cloudflare Tunnel** and **Tailscale**, and automated container package retention. + +--- + +## 1. Official Docker Packages & 3-Version Retention Policy + +Official multi-architecture Docker images (`linux/amd64` and `linux/arm64`) are published to the GitHub Container Registry (GHCR): + +```bash +# Pull latest stable release +docker pull ghcr.io/pathbit/ominirtksync:latest +``` + +### Automated Package Retention (Last 3 Versions) + +To ensure high availability, rollback safety, and clean storage, the GitHub Actions CI/CD pipeline enforces an automated package retention policy: +- **Always keeps the last 3 versions**: the active `latest` tag plus the 2 most recent tagged releases / commit SHAs. +- Multi-architecture manifest lists are resolved before deleting orphan manifests, ensuring platform layers remain fully functional. +- Runs automatically after every successful release build and on a weekly schedule. + +> [!NOTE] +> **GHCR Visibility & Permissions**: GitHub Container Registry packages in organizations default to Private upon initial push. If `docker pull` returns `unauthorized`, an organization administrator must navigate to `github.com/orgs/pathbit/packages/container/ominirtksync/settings` and set the package visibility to **Public**. + +--- + +## 2. Quick Start with Standalone Docker + +If you already have an OmniRoute gateway running on your host machine or network: + +```bash +docker run -d \ + --name ominirtk-sync \ + --restart unless-stopped \ + -p 127.0.0.1:9092:9090 \ + -v omniroute_data:/app/data \ + -v "${HOME}:/root/host:ro" \ + -v ominirtksync_logs:/app/logs \ + -e DB_PATH=/app/data/storage.sqlite \ + -e OMNIROUTE_URL=http://host.docker.internal:20128 \ + -e DASHBOARD_USER=admin \ + -e DASHBOARD_PASSWORD=your-secure-password \ + ghcr.io/pathbit/ominirtksync:latest +``` + +--- + +## 3. Production Deployment with Docker Compose + +The standard production setup runs OmniRoute (gateway) and OminiRTkSync (synchronizer) on an isolated internal management network (`ominirtksync-net`), with optional shared inference networking (`rtk-inference-net`). + +### Step 1: Initialize Configuration + +```bash +cp .env.example .env +# Edit .env and configure INITIAL_PASSWORD, JWT_SECRET, and DASHBOARD_PASSWORD +``` + +### Step 2: Launch Stack + +```bash +docker compose -f docker-compose.example.yml up -d +``` + +### Service Map and Port Allocation + +| Service | Container Name | Internal Port | Host Published Port | Purpose | +| :--- | :--- | :--- | :--- | :--- | +| **OmniRoute** | `ominirtk-router` | `20128` | `127.0.0.1:8082` | Gateway API & Admin | +| **OminiRTkSync** | `ominirtk-sync` | `9090` | `127.0.0.1:9092` | Guardian Dashboard & Healthz | +| **Headroom** *(optional)* | `ominirtk-headroom` | `8787` | `127.0.0.1:8787` | Token Compression Proxy | + +Dashboard access: **http://localhost:9092** + +--- + +## 4. Token & Cost Optimization: Headroom & Caveman + +AI coding agents (such as **Claude Code**, **Cursor**, **Windsurf**, and **Roo Code**) consume vast amounts of tokens when sending large files, terminal logs, git diffs, and conversational explanations. Using **Headroom** and **Caveman** together drastically cuts token consumption and prevents rate limits. + +``` +┌────────────────────────────────┐ +│ Coding Agent / Developer │ +│ (Claude Code / Cursor) │ +└───────────────┬────────────────┘ + │ + ▼ +┌────────────────────────────────┐ +│ Caveman (Plugin/Skill) │ <-- Minimizes OUTPUT tokens +│ (Enforces concise responses) │ +└───────────────┬────────────────┘ + │ + ▼ +┌────────────────────────────────┐ +│ Headroom (Proxy: 8787) │ <-- Compresses INPUT tokens +│ (Trims logs, AST & context) │ +└───────────────┬────────────────┘ + │ + ▼ +┌────────────────────────────────┐ +│ OmniRoute (Gateway: 8082) │ <-- Routing & Relational Mapping +└───────────────▲────────────────┘ + │ +┌───────────────┴────────────────┐ +│ OminiRTkSync (Guardian: 9092) │ <-- OAuth renewal & rate-limit healing +└────────────────────────────────┘ +``` + +### Headroom: Input Token Compression Proxy + +Headroom acts as a middleware proxy sitting between your coding agent and OmniRoute: +- Analyzes context payloads, logs, git diffs, and structured JSON. +- Compresses input tokens by 20% to 80% without losing critical code semantics. +- To start with Docker Compose: + +```bash +docker compose -f docker-compose.example.yml --profile headroom up -d +``` + +Configure your coding tool to point to Headroom (`http://127.0.0.1:8787/v1`) with OmniRoute credentials. Headroom automatically proxies optimized requests to `http://ominirtk-router:20128`. + +### Caveman: Output Token Reduction Skill + +While Headroom compresses what the LLM *reads*, Caveman minimizes what the LLM *writes*: +- Enforces an ultra-terse, compact agent communication style ("concise mode"). +- Strips conversational filler, preamble, and pleasantries while maintaining strict accuracy for code edits and terminal actions. +- Configured in Claude Code (`settings.local.json` prompt instructions) or agent system instructions. + +--- + +## 5. Remote Access: Cloudflare Tunnel & Tailscale + +By default, ports are bound to `127.0.0.1` for loopback security. When you need remote access from laptops, mobile devices, or team members, enable Cloudflare Tunnel or Tailscale. + +> [!WARNING] +> **Security Prerequisite**: Before enabling any public tunnel or remote exposure, you **must** set: +> 1. `REQUIRE_LOGIN=true` (with a strong custom password) +> 2. `REQUIRE_API_KEY=true` (for coding tool authentication) +> Exposing the gateway without these settings allows anyone with the URL to consume your LLM balances. + +### Option A: Cloudflare Quick Tunnel (Ephemeral URL) + +Useful for temporary demonstrations and remote testing without domain setup: + +```bash +docker compose -f docker-compose.example.yml --profile tunel up -d +``` + +View the generated `https://...trycloudflare.com` URL in container logs: + +```bash +docker logs ominirtk-tunel +``` + +### Option B: Cloudflare Named Tunnel (Persistent Domain) + +For permanent custom domains (`omni.yourdomain.com`) with Cloudflare Zero Trust: + +1. Create a tunnel in the Cloudflare Zero Trust dashboard. +2. Add your tunnel token to `.env`: + ```bash + TUNNEL_TOKEN=eyJhIjoi... + ``` +3. Start the tunnel profile: + ```bash + docker compose -f docker-compose.example.yml --profile tunel up -d + ``` + +### Option C: Tailscale (Private Zero-Trust Tailnet — Recommended) + +The safest method: your gateway joins your private tailnet and is never exposed to the public internet. + +1. Generate an ephemeral or reusable auth key at `https://login.tailscale.com/admin/settings/keys`. +2. Add `TS_AUTHKEY` to `.env`: + ```bash + TS_AUTHKEY=tskey-auth-... + ``` +3. Start the tailnet container: + ```bash + docker compose -f docker-compose.example.yml --profile tailnet up -d + ``` +4. Access via MagicDNS at `http://ominirtk:20128` or Tailscale IP `100.x.y.z:20128`. + +Alternatively, install Tailscale directly on the host machine: + +```bash +curl -fsSL https://tailscale.com/install.sh | sh +sudo tailscale up +tailscale ip -4 +``` + +--- + +## 6. Container Healthchecks & Monitoring + +Verify the status of all services: + +```bash +docker compose -f docker-compose.example.yml ps +``` + +The synchronizer exposes `/healthz` on port 9090 (host 9092): +- `OK` (HTTP 200): Synchronizer active and gateway reachable. +- `DATABASE_NOT_READY` (HTTP 503): Database path not found. +- `GATEWAY_SERVICE_UNREACHABLE` (HTTP 503): OmniRoute gateway not answering. + +--- + +*(Versão em Português)* + +# Guia de Implantação via Docker e Docker Compose + +Guia completo para implantar o **OminiRTkSync** e o **OmniRoute** via Docker e Docker Compose, com otimização de tokens via **Headroom** e **Caveman**, acesso remoto seguro via **Cloudflare Tunnel** e **Tailscale**, e retenção automatizada de imagens no GitHub Packages. + +## 1. Pacotes Oficiais e Política de Retenção de 3 Versões + +As imagens oficiais multi-arquitetura (`linux/amd64` e `linux/arm64`) são geradas e publicadas no GitHub Container Registry (GHCR): + +```bash +docker pull ghcr.io/pathbit/ominirtksync:latest +``` + +### Retenção Automática das 3 Últimas Versões + +O pipeline do GitHub Actions garante que: +- **Sempre mantemos as 3 versões mais recentes**: a tag ativa `latest` mais as 2 versões/tags marcadas anteriores. +- Os manifestos multi-plataforma são resolvidos antes da limpeza para evitar a quebra de camadas. +- A limpeza ocorre ao término de cada build de release e em agendamento semanal. + +> [!NOTE] +> **Visibilidade no GHCR**: Por padrão de segurança do GitHub, pacotes criados sob organizações nascem com visibilidade Privada. Se o comando `docker pull` responder com `unauthorized`, o administrador da organização no GitHub deve acessar as configurações do pacote (`github.com/orgs/pathbit/packages/container/ominirtksync/settings`) e alterar a visibilidade para **Public**. + +## 2. Implantação Rápida com Docker Run + +Para executar o sincronizador apontando para um OmniRoute já existente: + +```bash +docker run -d \ + --name ominirtk-sync \ + --restart unless-stopped \ + -p 127.0.0.1:9092:9090 \ + -v omniroute_data:/app/data \ + -v "${HOME}:/root/host:ro" \ + -v ominirtksync_logs:/app/logs \ + -e DB_PATH=/app/data/storage.sqlite \ + -e OMNIROUTE_URL=http://host.docker.internal:20128 \ + -e DASHBOARD_USER=admin \ + -e DASHBOARD_PASSWORD=sua-senha-segura \ + ghcr.io/pathbit/ominirtksync:latest +``` + +## 3. Implantação Completa com Docker Compose + +```bash +# 1. Prepare as variáveis de ambiente +cp .env.example .env + +# 2. Inicie a stack +docker compose -f docker-compose.example.yml up -d +``` + +Acesse o painel web em: **http://localhost:9092** + +## 4. Otimização de Tokens: Headroom e Caveman + +A combinação de **Headroom** e **Caveman** atua em duas frentes complementares: +1. **Headroom (Entrada/Input):** Middleware proxy que intercepta context windows, logs de compilação e comandos git diff, compactando a carga antes do envio ao OmniRoute. Ative via perfil: + ```bash + docker compose -f docker-compose.example.yml --profile headroom up -d + ``` + Aponte seus clientes para `http://127.0.0.1:8787/v1`. +2. **Caveman (Saída/Output):** Instrução de estilo conciso para agentes (Claude Code / Cursor) que elimina rodeios e respostas prolixas, gerando respostas diretas e economizando 30% a 60% de tokens de saída. + +## 5. Acesso Remoto: Cloudflare Tunnel e Tailscale + +Regra essencial de segurança: antes de expor qualquer rota, ative `REQUIRE_LOGIN=true` e `REQUIRE_API_KEY=true`. + +- **Cloudflare Tunnel Rápido:** `docker compose -f docker-compose.example.yml --profile tunel up -d` +- **Cloudflare Tunnel Nomeado:** Preencha `TUNNEL_TOKEN` no `.env` e suba o perfil `tunel`. +- **Tailscale (VPN Privada):** Preencha `TS_AUTHKEY` no `.env` e execute `docker compose -f docker-compose.example.yml --profile tailnet up -d`. diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index 5f26cb5..c59289b 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -16,6 +16,7 @@ republishes these pages automatically. Editing a page directly here will be over | Page | What it covers | | :--- | :--- | | [Installation](Installation) | Docker Compose and local virtual environment | +| [Docker Deployment](Docker-Deployment) | Docker run, Compose, Headroom, Caveman, Tunnel, Tailscale | | [Configuration](Configuration) | Every environment variable — the full headless contract | | [Dashboard](Dashboard) | The server-rendered panel, language switcher, cron logs | | [Authentication](Authentication) | Credentials, headless mode, break-glass recovery | diff --git a/docs/wiki/Installation.md b/docs/wiki/Installation.md index f2cd996..27ae9eb 100644 --- a/docs/wiki/Installation.md +++ b/docs/wiki/Installation.md @@ -1,6 +1,7 @@ # Installation Two supported paths: Docker (recommended) and a local Python virtual environment. +For a complete guide covering Docker run, Compose, Headroom, Caveman, Tunnel, and Tailscale, see [Docker Deployment](Docker-Deployment). --- diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md index 388e60b..387c703 100644 --- a/docs/wiki/_Sidebar.md +++ b/docs/wiki/_Sidebar.md @@ -2,6 +2,7 @@ - [Home](Home) - [Installation](Installation) +- [Docker Deployment](Docker-Deployment) - [Configuration](Configuration) - [Dashboard](Dashboard) - [Authentication](Authentication) diff --git a/tools/valida_docs.py b/tools/valida_docs.py index 79cf03d..19e4bcc 100644 --- a/tools/valida_docs.py +++ b/tools/valida_docs.py @@ -53,7 +53,7 @@ # CLI deste produto. "--profile", "--env-file", "--remove-orphans", "--wait", "--wait-timeout", "--force-recreate", "--no-autoupdate", "--url", - "--token", "-d", "-f", + "--token", "-d", "-f", "--name", "--restart", } # Rotas do GATEWAY, nao do painel. A pagina de saida de rede cita a API do