DeploymentHelm · shipped

ClawQL — Deployment & Operations Guide

For platform engineers and operators · June 2026 Apache 2.0 / MIT · github.com/danielsmithdevelopment/ClawQL

Operator-focused tier docs and natural-language ops tables are in Operator target architecture (design). An opt-in operator scaffold (CRD + reconcile + tier-spec ConfigMaps) is available separately — see clawql-operator-helm.md (#255).

Before you start

What you can deploy today

Choose a deployment path

Quick start (Helm — recommended)

From a repo clone:

make local-k8s-up

Uses charts/clawql-mcp/values-docker-desktop.yaml: MCP at http://clawql-mcp.localhost/mcp, dashboard at http://clawql.localhost, document pipeline + optional Onyx + Nextcloud enabled by default.

Production-style install:

helm upgrade --install clawql ./charts/clawql-mcp \
  --namespace clawql \
  --create-namespace \
  --wait

See helm.md for values, secrets (External Secrets + Vault), optional NATS/Flink/Onyx, and idpCollaboration.

Verify health

curl -s http://clawql-mcp.localhost/healthz    # or your Ingress / port-forward URL
curl -s http://clawql.localhost/api/k8s/health # dashboard pod

MCP smoke (Streamable HTTP):

curl -s -X POST http://clawql-mcp.localhost/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Configuration essentials

Base URLs for document vendors are injected by the chart when subcharts are enabled — see idp-pipeline.md § Helm.

Day-2 operations (Helm)

Upgrade

helm upgrade clawql ./charts/clawql-mcp -n clawql -f your-values.yaml --wait

Image tags: set image.tag (MCP), documentPipeline.*.image.tag, onyx.*.image.tag as needed. Prefer rolling upgrades with --wait and watch kubectl -n clawql get pods.

Secrets rotation

1. Update the Vault KV entry or Kubernetes Secret (ESO reconciles on interval).
2. Restart MCP if env is not hot-reloaded: kubectl -n clawql rollout restart deploy/clawql-mcp-http.

Document pipeline tokens (PAPERLESS_API_TOKEN, STIRLING_API_KEY, NEXTCLOUD_*, CONESHARE_API_TOKEN) live on chart-managed Secrets when auth.* blocks are set — see helm.md.

Scale

Adjust replicas on the MCP Deployment in values, or kubectl scale for quick tests. Document services (Tika, Gotenberg, Stirling) have their own Deployments under documentPipeline — scale independently under load.

Observability

• GET /metrics on MCP HTTP — Grafana dashboard (#210)
• Docker Desktop stack: docker-desktop-observability

Troubleshooting

Start with troubleshooting and helm.md. Common checks: provider auth env, bundled spec load (CLAWQL_PROVIDER), Ingress host DNS, and Paperless token from Profile / POST /api/token/ — the chart placeholder secrets are a starting point, the actual token comes from Paperless itself.

Local MCP without Kubernetes

git clone https://github.com/danielsmithdevelopment/ClawQL.git
cd ClawQL
npm ci && npm run build
cp .env.example .env   # set TIKA_BASE_URL, PAPERLESS_API_TOKEN, etc.
npm run start:http

When no spec env is set, the opinionated default stack loads (Cloudflare, GitHub, Slack, Linear, Notion, Onyx). Helm provider: default matches npm. Use CLAWQL_PROVIDER=all-providers or helm --set provider=all-providers for every bundled vendor plus Google top-50 and AWS top-50.

Operator scaffold (opt-in, shipped 7.0.0)

The operator scaffold reconciles ClawQLInstance CRs to tier-spec ConfigMaps and optionally rolls MCP when spec.mcp.rolloutOnTierSpecChange is set. Helm CLAWQL_ENABLE_* workflows remain the default when the operator is not installed.

1. Install CRD + reconcile: clawql-operator-helm.md
2. Apply a ClawQLInstance (examples/operator/clawqlinstance-minimal.yaml)
3. Mount the published tier-spec ConfigMap on MCP (instanceSpec.enabled: true)

Full tier/vertical/auth reconciliation and NL ops are in Operator target architecture (roadmap).

Related documentation

ClawQL Deployment & Operations Guide · June 2026 · Apache 2.0 / MIT

© Copyright 2026. All rights reserved. · ClawQL on GitHub