02 / Install & self-host

Kubernetes (Helm Charts)

On this page 9

Official Helm charts for deploying Synaplan and its infrastructure components on Kubernetes live in the synaplan-charts repository.

What's in the repository#

  • synaplan — the platform chart
  • triton — optional NVIDIA Triton Inference Server with TensorRT-LLM support

Synaplan uses BGE-M3 as its embedding model for RAG-powered semantic search across 100+ languages. Embeddings (and chat LLMs) run on whichever backend you configure:

  • Ollama — recommended for most deployments; simple setup, CPU and GPU inference, broad model support.
  • NVIDIA Triton — for production GPU clusters requiring maximum throughput with TensorRT-LLM optimized models.

Prerequisites#

  • Kubernetes 1.24+
  • Helm 3.14+
  • kubectl configured for your cluster

Install from GHCR#

Charts are published to the GitHub Container Registry as OCI artifacts and are publicly accessible:

shell
# Stable release (recommended for production)
helm install synaplan oci://ghcr.io/metadist/synaplan-charts/synaplan --version 0.1.0
helm install triton oci://ghcr.io/metadist/synaplan-charts/triton --version 0.1.0

Stable releases (0.1.0, 0.2.0, …) are created from git tags and are immutable; development builds (0.0.0-dev.<commit>) are built from main on every push and are for testing only.

Install from source#

shell
git clone https://github.com/metadist/synaplan-charts.git
cd synaplan-charts
helm install synaplan ./charts/synaplan
helm install triton ./charts/triton

Office documents (Collabora CODE)#

The charts do not yet ship a Collabora sidecar. Office thumbnails, PDF export, preview and combine need OFFICE_CONVERT_URL on the web and worker pods, pointing at CODE in the cluster or at an existing instance (Nextcloud / OpenCloud Collabora is fine for convert-to).

yaml
env:
  - name: OFFICE_CONVERT_URL
    value: http://collabora.office.svc.cluster.local:9980
  - name: OFFICE_CONVERT_TIMEOUT_MS
    value: "60000"

Collabora never sees Synaplan users — convert-to is a file POST. Identity stays in Synaplan. Full integrator notes (healthcheck, image pin, 403 / net.post_allow, future WOPI): synaplan-charts docs/collabora-office-engine.md and Office documents.

Research#

A research run is a series of short background jobs on the worker, on the async_ai_high transport — the same queue as other AI jobs. worker.transports must include async_ai_high. The chart default is async_ai_high async_extract async_index. If that transport is missing, a run waits, and after five minutes Operate → Feature Status says "No worker has picked up research units for 5 minutes."

Each thorough run uses about 1–3 MB of Redis while it works, and a few hundred KB after the report is delivered. The record is kept for 48 hours after the last change. The web pods do not keep the run. A shared Redis is required, the same one the rest of the cluster already uses for queues.

Research is off until an administrator turns it on. See Administration and Research in Desktop.

Air-gapped installs#

To keep the catalog on local providers, install with examples/values-airgap.yaml:

shell
helm install synaplan ./charts/synaplan -f examples/values-airgap.yaml

That soft-disables every catalog provider except Ollama, Piper, and Whisper, and sets WEB_SPEECH_ENABLED=false. Pull the Ollama models before users sign in. Walkthrough: Air-gapped installation. How the picker decides what to show: AI providers & models.

Restricting SSO access#

With oidc.enabled, everyone who can sign in at the identity provider gets an account by default. oidc.accessPolicy limits the instance to one organization, a role or a set of permissions, and oidc.accessPolicy.allowUserProvisioning: false stops a first sign-in from creating an account. The render fails when it is set on an image older than 5.4.0, which would ignore the rules. Values, a Kinde example, and what refused users see: SSO Access Restrictions.

Example deployment#

A complete example with Synaplan, Triton, and MariaDB (driven by helmfile) is available at deployments/synaplan-with-triton/ — see its README for prerequisites and configuration options.


For chart values, configuration reference, and the release process, use the synaplan-charts repository directly — its READMEs are generated from the charts and always current.