@fazer-ai/agents 1.0.0

package/dist/skills/agents-onboarding/templates/chatwoot/docker-compose.yml

@@ -0,0 +1,139 @@
+# Chatwoot for fazer.ai: GENERIC flavor (Portainer / EasyPanel / Dokploy / plain Docker).
+#
+# ONE file, BOTH editions, selected by env (see ./README.md):
+#   - OSS (no hub subscription): defaults, our public `ghcr.io/fazer-ai/chatwoot` fork, no Baileys.
+#   - Pro (hub subscription): set CHATWOOT_IMAGE to the Harbor image AND COMPOSE_PROFILES=pro
+#     (adds the Baileys WhatsApp provider). Requires `docker login harbor.fazer.ai` with the
+#     license registry credential (hub: generate_install_script).
+#
+# Secrets come from a .env you fill in (see ./.env.example); Coolify generates those automatically,
+# so it has its own file (./docker-compose.coolify.yml). TLS + reverse proxy are EXTERNAL: this stack
+# only publishes Chatwoot's HTTP port on the host (default 127.0.0.1:3001); terminate TLS in front
+# (the fazer.ai agents bundled Caddy can front chatwoot.<domain> at it; see the agents-onboarding skill).
+#
+#   cp .env.example .env   # fill every CHANGE_ME, then:
+#   docker compose up -d                         # OSS
+#   COMPOSE_PROFILES=pro docker compose up -d     # Pro (after the Harbor login)
+
+x-chatwoot-env: &chatwoot-env
+  NODE_ENV: production
+  RAILS_ENV: production
+  INSTALLATION_ENV: docker
+  DEFAULT_LOCALE: '${CHATWOOT_LOCALE:-en}'
+  LOG_LEVEL: '${RAILS_LOG_LEVEL:-info}'
+  FRONTEND_URL: '${CHATWOOT_URL}'
+  INTERNAL_HOST_URL: 'http://chatwoot:3000'
+  POSTGRES_HOST: postgres
+  POSTGRES_PORT: '5432'
+  POSTGRES_USERNAME: '${POSTGRES_USER}'
+  POSTGRES_PASSWORD: '${POSTGRES_PASSWORD}'
+  POSTGRES_DATABASE: '${POSTGRES_DB:-chatwoot_production}'
+  SECRET_KEY_BASE: '${SECRET_KEY_BASE}'
+  REDIS_URL: 'redis://redis:6379'
+  REDIS_PASSWORD: '${REDIS_PASSWORD}'
+  # Pro-only (Baileys WhatsApp): harmless on OSS (no Baileys inbox can be created there).
+  BAILEYS_PROVIDER_DEFAULT_CLIENT_NAME: '${BAILEYS_CLIENT_NAME:-Chatwoot}'
+  BAILEYS_PROVIDER_DEFAULT_URL: 'http://baileys-api:3025'
+  BAILEYS_PROVIDER_DEFAULT_API_KEY: '${BAILEYS_DEFAULT_API_KEY:-}'
+  BAILEYS_PROVIDER_USE_INTERNAL_HOST_URL: 'true'
+
+services:
+  chatwoot:
+    # OSS default (our fork); for Pro set CHATWOOT_IMAGE=harbor.fazer.ai/chatwoot/fazer-ai/chatwoot-pro:latest
+    image: '${CHATWOOT_IMAGE:-ghcr.io/fazer-ai/chatwoot:latest}'
+    pull_policy: always
+    volumes:
+      - 'storage:/app/storage'
+    depends_on:
+      postgres: { condition: service_healthy }
+      redis: { condition: service_healthy }
+    environment: *chatwoot-env
+    entrypoint: docker/entrypoints/rails.sh
+    command:
+      - sh
+      - '-c'
+      - 'bundle exec rails db:chatwoot_prepare && exec bundle exec rails s -p 3000 -b 0.0.0.0'
+    ports:
+      # Host:container. Front with your own TLS-terminating reverse proxy; bound to localhost by default.
+      - '${CHATWOOT_PORT:-127.0.0.1:3001}:3000'
+    restart: always
+    healthcheck:
+      test: ['CMD-SHELL', 'wget -qO- --header="Accept: text/html" http://127.0.0.1:3000/ || exit 1']
+      interval: 20s
+      timeout: 10s
+      retries: 10
+
+  sidekiq:
+    image: '${CHATWOOT_IMAGE:-ghcr.io/fazer-ai/chatwoot:latest}'
+    pull_policy: always
+    volumes:
+      - 'storage:/app/storage'
+    depends_on:
+      postgres: { condition: service_healthy }
+      redis: { condition: service_healthy }
+    environment: *chatwoot-env
+    command: ['bundle', 'exec', 'sidekiq', '-C', 'config/sidekiq.yml']
+    restart: always
+    healthcheck:
+      test: ['CMD-SHELL', 'ps aux | grep "[s]idekiq" || exit 1']
+      interval: 20s
+      timeout: 10s
+      retries: 5
+
+  postgres:
+    # pgvector (Chatwoot 4.x "Captain" AI uses the vector extension). Public image, no auth needed.
+    image: '${POSTGRES_IMAGE:-pgvector/pgvector:pg16}'
+    restart: always
+    volumes:
+      - 'postgres:/var/lib/postgresql/data'
+    environment:
+      POSTGRES_DB: '${POSTGRES_DB:-chatwoot_production}'
+      POSTGRES_USER: '${POSTGRES_USER}'
+      POSTGRES_PASSWORD: '${POSTGRES_PASSWORD}'
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -h localhost -p 5432 -U $${POSTGRES_USER} -d $${POSTGRES_DB}']
+      interval: 20s
+      timeout: 20s
+      retries: 10
+
+  redis:
+    image: 'redis:alpine'
+    restart: always
+    command: ['sh', '-c', 'redis-server --requirepass "$${REDIS_PASSWORD}"']
+    volumes:
+      - 'redis:/data'
+    environment:
+      REDIS_PASSWORD: '${REDIS_PASSWORD}'
+    healthcheck:
+      test: ['CMD-SHELL', 'redis-cli -h localhost -p 6379 -a $${REDIS_PASSWORD} ping | grep -q PONG']
+      interval: 20s
+      timeout: 20s
+      retries: 10
+
+  # Pro only: the Baileys WhatsApp provider. Starts ONLY with COMPOSE_PROFILES=pro.
+  baileys-api:
+    image: '${BAILEYS_IMAGE:-ghcr.io/fazer-ai/baileys-api:latest}'
+    profiles: ['pro']
+    pull_policy: always
+    volumes:
+      - 'storage:/app/storage'
+    environment:
+      NODE_ENV: production
+      REDIS_URL: 'redis://redis:6379'
+      REDIS_PASSWORD: '${REDIS_PASSWORD}'
+      LOG_LEVEL: '${BAILEYS_API_LOG_LEVEL:-info}'
+      BAILEYS_PROVIDER_DEFAULT_API_KEY: '${BAILEYS_DEFAULT_API_KEY}'
+    command: ['sh', '-c', 'bun manage-api-keys create user $${BAILEYS_DEFAULT_API_KEY} && bun start']
+    depends_on:
+      redis: { condition: service_healthy }
+    restart: always
+    healthcheck:
+      test: ['CMD-SHELL', 'wget -qO- http://localhost:3025/status || exit 1']
+      interval: 20s
+      timeout: 20s
+      retries: 10
+
+volumes:
+  storage:
+  postgres:
+  redis:

package/dist/skills/agents-onboarding/templates/docker-compose.coolify.yml

@@ -0,0 +1,73 @@
+services:
+  agents:
+    # Edition-driven: Free (default, public image) vs Pro — for Pro, set the AGENTS_IMAGE env on
+    # the Coolify service to the private Harbor image (project `agents`) AND register the Harbor
+    # registry credential in Coolify (hub: create_registry_credential, per-user, same as Chatwoot Pro).
+    # PLACEHOLDER: the public Free image is not published yet — swap `agents` once it exists.
+    image: '${AGENTS_IMAGE:-ghcr.io/fazer-ai/agents:latest}'
+    pull_policy: always
+    volumes:
+      - 'storage:/app/storage'
+    environment:
+      - SERVICE_URL_AGENTS
+      - NODE_ENV=production
+      - PORT=${PORT:-3000}
+      - PUBLIC_URL=${SERVICE_URL_AGENTS}
+      - LOG_LEVEL=${LOG_LEVEL:-info}
+      - JWT_SECRET=${SERVICE_PASSWORD_64_JWTSECRET}
+      - ENCRYPTION_KEY=${SERVICE_PASSWORD_64_ENCRYPTIONKEY}
+      - CORS_ORIGIN=${CORS_ORIGIN:-*}
+      - CDN_URL=${SERVICE_URL_AGENTS}
+      # NOTE: opt this onboarding / self-hosted deploy into MCP Dynamic Client Registration so the
+      # operator's AI agent (Claude Code / Codex) can `mcp login` to THIS instance's MCP — OAuth DCR
+      # mints the client and the metadata then publishes `registration_endpoint`. The app code default
+      # is OFF (closed/hardened, see docs/mcp.md); this agent-operated deploy turns it ON deliberately.
+      - MCP_DCR_ENABLED=true
+      # Persist uploaded branding (logo/favicon) + generated quote PDFs on the `storage` volume.
+      # The defaults (./data/*) live on the ephemeral container FS and vanish on every redeploy.
+      - BRANDING_STORAGE_DIR=/app/storage/branding
+      - QUOTES_STORAGE_DIR=/app/storage/quotes
+      # NOTE: TWO roles by design. The superuser (SERVICE_USER_DBUSER, also the postgres
+      # container's owner) runs migrations + bootstrap. The app role (SERVICE_USER_APPDBUSER,
+      # created by db-bootstrap.ts) is NON-superuser/NON-bypassrls so RLS isolation holds — the
+      # boot guard refuses to start the server on a privileged runtime role.
+      - 'MIGRATION_DATABASE_URL=postgres://${SERVICE_USER_DBUSER}:${SERVICE_PASSWORD_64_DBPASSWORD}@${DATABASE_HOST:-postgres}:${DATABASE_PORT:-5432}/${DATABASE_NAME:-secretaria_v4_db}'
+      - 'DATABASE_URL=postgres://${SERVICE_USER_APPDBUSER}:${SERVICE_PASSWORD_64_APPDBPASSWORD}@${DATABASE_HOST:-postgres}:${DATABASE_PORT:-5432}/${DATABASE_NAME:-secretaria_v4_db}'
+      - 'LANGGRAPH_DATABASE_URL=postgres://${SERVICE_USER_APPDBUSER}:${SERVICE_PASSWORD_64_APPDBPASSWORD}@${DATABASE_HOST:-postgres}:${DATABASE_PORT:-5432}/${DATABASE_NAME:-secretaria_v4_db}'
+    # NOTE: the boot sequence (provision runtime role -> migrate as owner -> run the interpreted
+    # server) is the image CMD in the Dockerfile. Do NOT override `command` here: it once drifted to
+    # a stale `./server` (from the pre-interpreted `bun build --compile` era) and crash-looped on
+    # `exec: ./server: not found` while the image CMD stayed correct.
+    restart: always
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - 'wget -qO- http://localhost:3000/api/health'
+      interval: 20s
+      timeout: 10s
+      retries: 5
+    depends_on:
+      postgres:
+        condition: service_healthy
+  postgres:
+    # pgvector image (NOT plain postgres): the schema needs CREATE EXTENSION vector. pg17 matches
+    # the validated isolation spike.
+    image: 'pgvector/pgvector:pg17'
+    restart: always
+    volumes:
+      - 'postgres:/var/lib/postgresql/data'
+    environment:
+      - POSTGRES_DB=${DATABASE_NAME:-secretaria_v4_db}
+      - POSTGRES_USER=${SERVICE_USER_DBUSER}
+      - POSTGRES_PASSWORD=${SERVICE_PASSWORD_64_DBPASSWORD}
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - 'pg_isready -h localhost -p 5432 -U $${POSTGRES_USER} -d $${POSTGRES_DB}'
+      interval: 20s
+      timeout: 20s
+      retries: 10
+
+volumes:
+  storage:
+  postgres:

package/dist/skills/agents-onboarding/templates/docker-compose.portainer.yml

@@ -0,0 +1,132 @@
+# Self-contained production stack for fazer.ai agents on Portainer (Tier B deploy) — and any host where
+# you want TLS terminated INSIDE the stack instead of by an external proxy.
+#
+# Difference vs docker-compose.prod.yml: prod.yml only publishes the app's HTTP port and expects you to
+# bring your own reverse proxy (Traefik/Caddy/NPM). THIS file bundles a Caddy service that terminates TLS
+# and obtains a REAL certificate automatically (Let's Encrypt / ZeroSSL via the HTTP-01 challenge) for
+# CADDY_DOMAIN — no Traefik labels, no Docker-socket polling. That is the Tier B "agent brings up Caddy"
+# path in the onboarding plan.
+#
+# WHY SELF-CONTAINED (not a `-f` override of prod.yml): Portainer's "deploy from string" API
+# (POST /api/stacks/create/standalone/string) accepts ONE compose document, so this file repeats prod.yml's
+# agents + postgres verbatim and adds caddy. Keep those two blocks in sync with docker-compose.prod.yml.
+#
+# Fill the env with:
+#   bun scripts/gen-onboarding-env.ts --public-url https://agentes.example.com [--acme-email you@example.com]
+# It emits CADDY_DOMAIN + the two-role DB URLs + secrets. On Portainer, paste this file as a Stack and set
+# the same variables in the Stack env editor (or pass them as the API's Env[] array). To also serve the
+# Portainer UI itself on a clean HTTPS domain, set PORTAINER_DOMAIN (e.g. portainer.example.com) — Caddy
+# adds a second site reverse-proxying to the host's Portainer (9443, self-signed upstream).
+#
+# TWO database roles by design (docs/deploy.md): MIGRATION_DATABASE_URL = superuser (migrate + bootstrap);
+# DATABASE_URL / LANGGRAPH_DATABASE_URL = NON-superuser runtime role (RLS holds; the boot guard enforces it).
+# SINGLE replica by construction (scheduler / debounce / webhook / alert workers + realtime pub/sub are
+# single-process). Do NOT scale agents to >1 here.
+
+services:
+  caddy:
+    image: 'caddy:2'
+    restart: always
+    depends_on:
+      - agents
+    ports:
+      - '80:80'
+      - '443:443'
+    extra_hosts:
+      # Lets the optional Portainer-panel site (PORTAINER_DOMAIN) reach the host's Portainer UI on 9443.
+      - 'host.docker.internal:host-gateway'
+    environment:
+      - CADDY_DOMAIN=${CADDY_DOMAIN}
+      - ACME_EMAIL=${ACME_EMAIL:-}
+      - PORTAINER_DOMAIN=${PORTAINER_DOMAIN:-}
+      - PORTAINER_UPSTREAM=${PORTAINER_UPSTREAM:-https://host.docker.internal:9443}
+    # Build a Caddyfile from env at start (a string-only Portainer deploy ships no files), then run it.
+    # `$$VAR` is escaped from compose interpolation so the SHELL expands it at runtime from `environment:`;
+    # `${VAR}` in `environment:` above IS interpolated by compose from the stack env / .env.
+    entrypoint:
+      - sh
+      - -ceu
+      - |
+        cf=/etc/caddy/Caddyfile
+        : > "$$cf"
+        if [ -n "$${ACME_EMAIL}" ]; then
+          printf '{\n\temail %s\n}\n' "$${ACME_EMAIL}" >> "$$cf"
+        fi
+        printf '%s {\n\treverse_proxy agents:3000\n}\n' "$${CADDY_DOMAIN}" >> "$$cf"
+        if [ -n "$${PORTAINER_DOMAIN}" ]; then
+          printf '%s {\n\treverse_proxy %s {\n\t\ttransport http {\n\t\t\ttls_insecure_skip_verify\n\t\t}\n\t}\n}\n' "$${PORTAINER_DOMAIN}" "$${PORTAINER_UPSTREAM}" >> "$$cf"
+        fi
+        echo '----- generated Caddyfile -----'
+        cat "$$cf"
+        echo '-------------------------------'
+        exec caddy run --config "$$cf" --adapter caddyfile
+    volumes:
+      - 'caddy_data:/data'
+      - 'caddy_config:/config'
+
+  agents:
+    # Edition-driven: Free (default, public image) vs Pro (set AGENTS_IMAGE to the private
+    # Harbor image, project `agents`, after `docker login` — hub: create_registry_credential, per-user).
+    # PLACEHOLDER: the public Free image is not published yet — swap `agents` once it exists.
+    image: ${AGENTS_IMAGE:-ghcr.io/fazer-ai/agents:latest}
+    pull_policy: always
+    restart: always
+    # NOTE: no `command` here on purpose — the image entrypoint runs, in order: db-bootstrap.ts (idempotent
+    # runtime-role provisioning) → prisma migrate deploy → serve. Overriding risks drifting from that contract.
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+      - PUBLIC_URL=${PUBLIC_URL}
+      - CDN_URL=${PUBLIC_URL}
+      - CORS_ORIGIN=${CORS_ORIGIN:-*}
+      - LOG_LEVEL=${LOG_LEVEL:-info}
+      - JWT_SECRET=${JWT_SECRET}
+      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
+      # Superuser/owner connection — migrations + bootstrap only. Matches the postgres container creds below.
+      - MIGRATION_DATABASE_URL=${MIGRATION_DATABASE_URL}
+      # Runtime role — NON-superuser, NON-bypassrls (db-bootstrap creates it from this URL). RLS holds.
+      - DATABASE_URL=${DATABASE_URL}
+      # Checkpointer pool — MUST be the runtime (non-superuser) role, never the migration URL.
+      - LANGGRAPH_DATABASE_URL=${LANGGRAPH_DATABASE_URL}
+      # Persist uploaded branding + generated quote PDFs on the `storage` volume (defaults live on the
+      # ephemeral container FS and vanish on every redeploy).
+      - BRANDING_STORAGE_DIR=/app/storage/branding
+      - QUOTES_STORAGE_DIR=/app/storage/quotes
+    # No host port publish: Caddy is the only ingress and reaches the app over the compose network.
+    expose:
+      - '3000'
+    volumes:
+      - 'storage:/app/storage'
+    healthcheck:
+      test: ['CMD-SHELL', 'wget -qO- http://localhost:3000/api/health || exit 1']
+      interval: 20s
+      timeout: 10s
+      retries: 5
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  postgres:
+    # pgvector image (NOT plain postgres): the schema needs CREATE EXTENSION vector. pg17 matches the
+    # validated isolation spike. Not published to the host — only the app reaches it over the network.
+    image: 'pgvector/pgvector:pg17'
+    restart: always
+    environment:
+      - POSTGRES_DB=${DATABASE_NAME:-secretaria_v4_db}
+      - POSTGRES_USER=${POSTGRES_USER}
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
+    volumes:
+      - 'postgres:/var/lib/postgresql/data'
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - 'pg_isready -h localhost -p 5432 -U $${POSTGRES_USER} -d $${POSTGRES_DB}'
+      interval: 20s
+      timeout: 20s
+      retries: 10
+
+volumes:
+  storage:
+  postgres:
+  caddy_data:
+  caddy_config:

package/dist/skills/agents-onboarding/templates/docker-compose.prod.yml

@@ -0,0 +1,85 @@
+# Platform-neutral production stack for fazer.ai agents (Portainer / EasyPanel / plain `docker compose`
+# on a VM). Coolify has its own file (docker-compose.coolify.yml, magic-vars); THIS file reads plain
+# env vars from a .env you generate with `bun scripts/gen-onboarding-env.ts` (writes every secret/URL
+# below, consistently). TLS + reverse proxy are EXTERNAL (Caddy/Traefik/Nginx Proxy Manager): this
+# stack only publishes the app's HTTP port on the host — terminate TLS in front of it.
+#
+# TWO database roles by design (docs/deploy.md, load-bearing): the SUPERUSER (POSTGRES_USER, the
+# postgres container's owner) runs db-bootstrap + migrations; the NON-superuser runtime role (encoded
+# in DATABASE_URL, created by db-bootstrap from that URL) is what the server runs as, so Postgres RLS
+# isolation holds. The boot guard hard-crashes if the runtime role is privileged.
+#
+# SINGLE replica by construction (the scheduler / debounce / webhook / alert workers + realtime
+# pub/sub are single-process). Do NOT scale `agents` to >1 here. To add web replicas, run the
+# extras with SCHEDULER_WORKER_ENABLED/WEBHOOK_WORKER_ENABLED/DEBOUNCE_WORKER_ENABLED/
+# ALERT_WORKER_ENABLED=false and keep exactly one leader with them on (docs/deploy.md §4).
+
+services:
+  agents:
+    # Edition-driven: Free (default, public image) vs Pro (set AGENTS_IMAGE to the private
+    # Harbor image, project `agents`, after `docker login` — hub: create_registry_credential, per-user).
+    # PLACEHOLDER: the public Free image is not published yet — swap `agents` once it exists.
+    image: ${AGENTS_IMAGE:-ghcr.io/fazer-ai/agents:latest}
+    pull_policy: always
+    restart: always
+    # NOTE: no `command` here on purpose — the image's default entrypoint already runs, in order:
+    # db-bootstrap.ts (idempotent runtime-role provisioning) → prisma migrate deploy → serve
+    # interpreted (bun src/index.ts). Overriding risks drifting from that contract.
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+      - PUBLIC_URL=${PUBLIC_URL}
+      - CDN_URL=${PUBLIC_URL}
+      - CORS_ORIGIN=${CORS_ORIGIN:-*}
+      - LOG_LEVEL=${LOG_LEVEL:-info}
+      - JWT_SECRET=${JWT_SECRET}
+      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
+      # Superuser/owner connection — migrations + bootstrap only. Its user/password MUST match the
+      # postgres container's POSTGRES_USER/POSTGRES_PASSWORD below.
+      - MIGRATION_DATABASE_URL=${MIGRATION_DATABASE_URL}
+      # Runtime role — NON-superuser, NON-bypassrls (db-bootstrap creates it from this URL). RLS holds.
+      - DATABASE_URL=${DATABASE_URL}
+      # Checkpointer pool — MUST be the runtime (non-superuser) role, never the migration URL.
+      - LANGGRAPH_DATABASE_URL=${LANGGRAPH_DATABASE_URL}
+      # Persist uploaded branding (logo/favicon) + generated quote PDFs on the `storage` volume
+      # (mounted below). The defaults (./data/*) live on the ephemeral container FS and vanish on
+      # every redeploy.
+      - BRANDING_STORAGE_DIR=/app/storage/branding
+      - QUOTES_STORAGE_DIR=/app/storage/quotes
+    ports:
+      # Host:container. Put a TLS-terminating reverse proxy in front; in untrusted networks bind to
+      # 127.0.0.1 (set APP_PORT=127.0.0.1:3000) or firewall the port.
+      - '${APP_PORT:-3000}:3000'
+    volumes:
+      - 'storage:/app/storage'
+    healthcheck:
+      test: ['CMD-SHELL', 'wget -qO- http://localhost:3000/api/health || exit 1']
+      interval: 20s
+      timeout: 10s
+      retries: 5
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  postgres:
+    # pgvector image (NOT plain postgres): the schema needs CREATE EXTENSION vector. pg17 matches the
+    # validated isolation spike. Not published to the host — only the app reaches it over the network.
+    image: 'pgvector/pgvector:pg17'
+    restart: always
+    environment:
+      - POSTGRES_DB=${DATABASE_NAME:-secretaria_v4_db}
+      - POSTGRES_USER=${POSTGRES_USER}
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
+    volumes:
+      - 'postgres:/var/lib/postgresql/data'
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - 'pg_isready -h localhost -p 5432 -U $${POSTGRES_USER} -d $${POSTGRES_DB}'
+      interval: 20s
+      timeout: 20s
+      retries: 10
+
+volumes:
+  storage:
+  postgres:

package/dist/skills/agents-onboarding/templates/langfuse/.env.example

@@ -0,0 +1,59 @@
+# Langfuse v3 self-hosted: env for the GENERIC flavor (docker-compose.yml).
+# Coolify users do NOT need this file (magic vars are auto-generated); see docker-compose.coolify.yml.
+#
+#   cp .env.example .env   &&   fill every CHANGE_ME   &&   docker compose up -d
+#
+# Generate strong secrets, e.g.:
+#   openssl rand -base64 32                  # SALT, NEXTAUTH_SECRET, passwords
+#   openssl rand -hex 32                     # ENCRYPTION_KEY (MUST be 64 hex chars / 256-bit)
+#   openssl rand -hex 16                     # MinIO user/password are arbitrary, just keep them secret
+
+# ── public URL (where the browser/SDK reach Langfuse; include scheme) ──
+LANGFUSE_PUBLIC_URL=https://langfuse.example.com
+LANGFUSE_PORT=3000
+
+# ── app secrets ──
+LANGFUSE_SALT=CHANGE_ME_base64_32
+LANGFUSE_ENCRYPTION_KEY=CHANGE_ME_hex_64   # exactly 64 hex chars
+LANGFUSE_NEXTAUTH_SECRET=CHANGE_ME_base64_32
+
+# ── postgres ──
+POSTGRES_DB=langfuse-db
+POSTGRES_USER=langfuse
+POSTGRES_PASSWORD=CHANGE_ME
+
+# ── clickhouse ──
+CLICKHOUSE_DB=default
+CLICKHOUSE_USER=clickhouse
+CLICKHOUSE_PASSWORD=CHANGE_ME
+
+# ── redis ──
+REDIS_PASSWORD=CHANGE_ME
+
+# ── MinIO (blob storage: MANDATORY; the compose points all S3 families here) ──
+MINIO_ROOT_USER=langfuse-minio
+MINIO_ROOT_PASSWORD=CHANGE_ME
+
+# ── optional: SMTP for invitations / password resets (blank = disabled) ──
+LANGFUSE_EMAIL_FROM=admin@example.com
+LANGFUSE_SMTP_URL=
+
+# ── headless seed (agent-driven; see references/05-langfuse.md), Langfuse's recommended pattern ──
+# The agent provisions EVERYTHING on the first boot: a user (org OWNER) + org + project + key pair, with
+# AUTH_DISABLE_SIGNUP=true from the start, so signup is never open (Langfuse has no "first admin then
+# close" gate; open signup would let anyone register on the exposed instance). The operator SIGNS IN at
+# /auth/sign-in with the seeded email + password (and changes it); the agent already holds the keys and
+# wires them into fazer.ai agents. One deploy, no open signup window.
+# The USER requires the ORG (seed them together); Langfuse upserts by id, so a redeploy does not duplicate.
+# Password: include a non-alphanumeric char (Langfuse's policy for signup/change; seed + login accept
+# without, but be safe). Leave every LANGFUSE_INIT_* blank for a plain deploy with no seed.
+AUTH_DISABLE_SIGNUP=true
+LANGFUSE_INIT_USER_EMAIL=
+LANGFUSE_INIT_USER_NAME=
+LANGFUSE_INIT_USER_PASSWORD=
+LANGFUSE_INIT_ORG_ID=
+LANGFUSE_INIT_ORG_NAME=
+LANGFUSE_INIT_PROJECT_ID=
+LANGFUSE_INIT_PROJECT_NAME=
+LANGFUSE_INIT_PROJECT_PUBLIC_KEY=
+LANGFUSE_INIT_PROJECT_SECRET_KEY=

package/dist/skills/agents-onboarding/templates/langfuse/README.md

@@ -0,0 +1,132 @@
+# Langfuse (self-hosted) for fazer.ai
+
+Optional companion service for **agent tracing**. Langfuse is wired into fazer.ai agents **per-tenant
+via a `langfuse` vault credential** (never a global env var); see `docs/deploy.md`
+and `docs/graph.md`. This folder vendors a deploy that actually works, in the
+project's three flavors (Coolify primary; Portainer and a generic "Outros" path, per
+`docs/deploy.md`).
+
+## Why this exists (the bug the one-click hides)
+
+Langfuse v3 **requires S3-compatible blob storage for ingestion**: on every
+`POST /api/public/ingestion`, the web container uploads the raw event JSON to S3 **before** queueing
+it to ClickHouse. The official Langfuse one-click / Coolify template declares the `LANGFUSE_S3_*`
+variable **names** but ships them **empty** and bundles **no** object-storage service.
+
+Result, observed in production-like testing:
+
+- `GET /api/public/projects` reads **Postgres only** → returns `200`. A naive "test connection"
+  (which is exactly what the Langfuse credential test does) **passes**, so the instance looks healthy.
+- `POST /api/public/ingestion` tries to upload to S3 with empty creds → the AWS SDK throws
+  `Could not load credentials from any providers` → `Failed to upload events to blob storage,
+  aborting event processing` → **HTTP 500** (plain text, not JSON).
+- The Langfuse client SDK then chokes parsing the non-JSON 500 body, and in its background flush
+  path the error is swallowed. Net effect: **traces silently never arrive**, with no client-side
+  error and nothing in the producing app's logs.
+
+This is **not** a bug in fazer.ai agents (the trace handler builds, enqueues, and POSTs correctly) and
+**not** a flush/runtime issue: it is a missing-storage deploy gap. These compose files bundle
+**MinIO** and wire all three S3 families (`EVENT_UPLOAD`, `MEDIA_UPLOAD`, `BATCH_EXPORT`) to it.
+
+## Files
+
+| File | Use |
+| --- | --- |
+| `docker-compose.coolify.yml` | **Coolify** (primary). Uses Coolify magic vars (`SERVICE_*`); secrets auto-generated. |
+| `docker-compose.yml` | **Generic**: Portainer / EasyPanel / Dokploy / plain Docker. Secrets from `.env`. |
+| `.env.example` | Template for the generic flavor. `cp .env.example .env`, fill every `CHANGE_ME`. |
+
+Both composes are identical in topology, `langfuse` (web) + `langfuse-worker` + `postgres` +
+`redis` + `clickhouse` + **`minio`**, and differ only in how secrets are supplied.
+
+## Deploy
+
+### Coolify (primary)
+
+1. New Resource → **Docker Compose** → paste `docker-compose.coolify.yml`.
+2. Set the service **Domain** to your Langfuse FQDN (Coolify fills `SERVICE_FQDN_LANGFUSE_3000` /
+   `SERVICE_URL_LANGFUSE`). Coolify generates `SERVICE_USER_MINIO`, `SERVICE_PASSWORD_MINIO`, and all
+   other `SERVICE_*` secrets automatically; **do not** set them by hand.
+3. Deploy. Confirm `minio` becomes healthy, then verify ingestion (below).
+
+> The blob-storage creds are the same Coolify magic vars used by the `minio` service, so the web,
+> the worker, and MinIO always agree without you copying a secret around. That is the point of using
+> magic vars here instead of hardcoded `LANGFUSE_S3_*` values.
+
+### Portainer / EasyPanel / Dokploy / plain Docker (generic)
+
+```sh
+cp .env.example .env      # fill every CHANGE_ME (see the openssl hints in the file)
+docker compose up -d
+```
+
+Portainer: paste `docker-compose.yml` as a Stack and provide the same variables via the Stack env
+editor instead of a `.env` file. Put your own TLS-terminating reverse proxy in front of port 3000.
+
+### Magic var ↔ generic env mapping
+
+| Coolify magic var | Generic `.env` | Purpose |
+| --- | --- | --- |
+| `SERVICE_USER_MINIO` / `SERVICE_PASSWORD_MINIO` | `MINIO_ROOT_USER` / `MINIO_ROOT_PASSWORD` | MinIO creds = the S3 access key/secret |
+| `SERVICE_USER_POSTGRES` / `SERVICE_PASSWORD_POSTGRES` | `POSTGRES_USER` / `POSTGRES_PASSWORD` | Postgres |
+| `SERVICE_USER_CLICKHOUSE` / `SERVICE_PASSWORD_CLICKHOUSE` | `CLICKHOUSE_USER` / `CLICKHOUSE_PASSWORD` | ClickHouse |
+| `SERVICE_PASSWORD_REDIS` | `REDIS_PASSWORD` | Redis |
+| `SERVICE_PASSWORD_SALT` | `LANGFUSE_SALT` | Langfuse salt |
+| `SERVICE_PASSWORD_64_LANGFUSE` | `LANGFUSE_ENCRYPTION_KEY` | 256-bit encryption key (64 hex) |
+| `SERVICE_BASE64_NEXTAUTHSECRET` | `LANGFUSE_NEXTAUTH_SECRET` | NextAuth secret |
+| `SERVICE_URL_LANGFUSE` | `LANGFUSE_PUBLIC_URL` | Public URL |
+
+## Seed everything headless (agent-driven, one deploy)
+
+The agent does **not** ask the user to copy keys out of the UI, and does **not** open signup. It
+provisions everything on the first boot (Langfuse's own recommended headless-init pattern):
+
+1. The agent generates a `pk-lf-…` / `sk-lf-…` key pair, an org id + name, a project id + name, and a
+   strong temporary password (include a non-alphanumeric char). The user email is the operator's, reused
+   from the Chatwoot admin so they have one login across tools.
+2. The agent sets, on the service env (Coolify) or `.env` (generic), and deploys **once** with
+   `AUTH_DISABLE_SIGNUP=true` (the template default):
+   - `LANGFUSE_INIT_USER_EMAIL` / `_NAME` / `_PASSWORD`
+   - `LANGFUSE_INIT_ORG_ID` / `_NAME`
+   - `LANGFUSE_INIT_PROJECT_ID` / `_NAME` / `_PUBLIC_KEY` / `_SECRET_KEY`
+
+   On boot Langfuse creates the **user (org OWNER) + org + project + keys**. The user requires the org
+   (seed them together); it upserts by id, so a redeploy never duplicates.
+3. The operator **signs in** at `/auth/sign-in` (never signs up) with the seeded email + the generated
+   password (the agent shows it) and changes it on first login. The seed is create-if-not-exists
+   (verified: the password change survives redeploys), so the operator's real password never passes
+   through the agent. The agent already holds the keys and wires them into fazer.ai agents (below).
+
+Empirically validated with this template's compose: the `LANGFUSE_INIT_USER` becomes org `OWNER`, the
+seeded user signs in (session shows `role: OWNER`), the seeded keys authenticate ingestion (`207`), and
+signup returns `422 Sign up is disabled` from the start, with no open-signup window.
+
+## Verify ingestion actually works
+
+A green health check is **not** enough (it only proves Postgres). Confirm a trace round-trips:
+
+```sh
+# 1) use the seeded pk-lf-…/sk-lf-… pair (or create one in the UI), then:
+PK=pk-lf-...; SK=sk-lf-...; BASE=https://langfuse.example.com
+
+# 2) POST a trace event, expect HTTP 207/200 (NOT 500):
+curl -s -u "$PK:$SK" -H 'Content-Type: application/json' -X POST "$BASE/api/public/ingestion" \
+  -d '{"batch":[{"id":"t1","type":"trace-create","timestamp":"2026-01-01T00:00:00.000Z","body":{"id":"verify-1","name":"verify"}}]}' \
+  -w '\n[http %{http_code}]\n'
+
+# 3) read it back (give the worker a few seconds to flush to ClickHouse):
+curl -s -u "$PK:$SK" "$BASE/api/public/traces?limit=5"
+```
+
+A `500` here means blob storage is still misconfigured: check the `langfuse` (web) container logs
+for `Failed to upload events to blob storage`.
+
+## Wire into fazer.ai agents
+
+Tracing is per-tenant. The agent uses the MCP **`langfuse_connect`** tool: it takes the public key +
+secret key + base URL inline, creates the `langfuse` vault credential, and turns tracing on in one call
+(`docs/mcp.md`). The equivalent by hand is a `langfuse` vault credential (`POST /v1/vault` with
+`kind:"langfuse"`, `value:{publicKey, secretKey}`, `baseUrl:"https://langfuse.example.com"`) then
+`PUT /v1/tenant-settings/langfuse {enabled:true, credentialRef:"vault:<id>"}`. The connection test on
+the credential checks reachability + auth (Postgres path); the **ingestion** verification above is what
+proves traces will land. See `references/05-langfuse.md`.