Architecture

This page is the conceptual map of an Octostar deployment: the layers that make up the platform, how the installer assembles them, how configuration resolves, and how traffic flows once it is running. Read it before a first install so the later procedure pages (Online, Air-gapped) make sense as a whole.

Octostar is a Helmfile-orchestrated distribution: one repository (octostar-singlenode) deploys the full analytics platform onto any conformant Kubernetes cluster. The same codebase serves three deployment modes (production, single-node demo, local development) and two network postures (online, air-gapped) — they differ in where images and charts come from, not in the architecture below.

Platform stack

Each layer runs on the one beneath it. Everything in the Octostar platform box deploys, by default, into a single Kubernetes (customizable) namespace (octostar-main as default).

Layer	What it provides
Core platform & AI/ML	The Octostar application itself — octostar-api, the scheduler, the web UI served via CDN/frontend, and the ML pipeline microservices (object detection, document extraction, audio transcription, image augmentation).
Workflow	Temporal for durable workflow execution.
Data & storage	ClickHouse (analytical store), MySQL, OpenSearch (search/index), PostgreSQL via the CloudNativePG operator, and SeaweedFS as the S3-compatible object store.
Observability	Prometheus + Grafana + Loki, with optional Tempo tracing. Grafana ships pre-loaded dashboards for the platform dependencies.
Cluster services (optional)	Common cluster prerequisites Octostar can install for you — cert-manager for TLS, the nginx ingress controller, and MetalLB for bare-metal load balancing. These are optional and swappable: bring your own if your cluster (or cloud) already provides them.
Kubernetes	Any conformant distribution. Octostar does not assume a specific cloud or CNI.

📝 Resource adaptation — The platform auto-adapts to the resources it finds. It runs in constrained single-node environments and scales up — more memory, more replicas — when additional nodes and resources are available. See Prerequisites for sizing.

Deployment architecture

bin/install.sh is the entry point. It detects the platform, installs missing prerequisites, and then drives Helmfile, which applies the service groups in dependency order. Each group is its own helmfile so it can be reasoned about — and, in development, applied — independently.

1. bin/install.sh — the only command an operator normally runs. Performs OS checks, optionally installs tools (--install-tools), and invokes Helmfile. update-existing.sh and destroy.sh are its upgrade and teardown counterparts.
2. helmfile.yaml — the top-level orchestrator that ties the stages together and pulls in the per-dependency helmfiles.
3. Staged sync — preps (secrets, cert-manager) → data → monitoring → core (octostar). Ordering guarantees that, for example, cert-manager exists before workloads that need certificates.
4. Per-dependency helmfiles — PostgreSQL, SeaweedFS, Temporal, Traefik, nginx, MetalLB, and others are split out so a single component can be applied or tuned in isolation.

💡 Targeted applies (advanced) — For development you can apply one stage directly, e.g. helmfile -f helmfile-data.yaml apply. For normal installs and upgrades use install.sh / update-existing.sh so ordering and prerequisites are handled for you. See Online installation.

Configuration model

Configuration resolves through three tiers, each overriding the previous. You normally edit only the last one.

• defaults.yaml — safe base defaults; never edited directly.
• versions.yaml — pinned component and image versions (the single source of truth the air-gap bundle is built against).
• local-env.yaml — your overrides. Created by copying local-env.template.yaml; every key is commented and shows its default, so an almost-empty file is valid.

Secrets are not stored loose: values from local-env.yaml are injected into the cluster as Kubernetes Secrets — the Docker registry credential (regcred), database passwords, API keys, and TLS material. Some values (notably several langfuse keys) are write-once at first install. Full reference: Configuration.

Namespacing, ingress & service discovery

All components deploy into a single, configurable namespace (octostar-main by default). Internal services resolve over cluster DNS at {service}.{namespace}.svc.cluster.local; externally, ingress hostnames follow {subdomain}.{domain}, where domain is set by octostar.domain (default local.test).

The three primary entry points are home.<domain> (platform UI), fusion.<domain> (the Fusion / timbr knowledge layer), and api.<domain>. TLS is self-signed for the internal local.test domain or supplied/ZeroSSL-issued for production — see Configuration → Certificates.

Network postures

The architecture above is identical online and air-gapped. What changes is the source of images and charts — the single most important distinction to grasp before installing.

• Online — nodes pull images from Docker Hub and charts from upstream Helm/OCI repositories. Requires a Docker Hub token. See Online installation.
• Air-gapped — images are mirrored into a private registry and rewritten at admission time by OPA Gatekeeper (AssignImage); charts are served from a vendored charts-offline/ directory instead of remote repos. The offline tooling patches install.sh and the helmfiles to remove every internet probe. See Air-gapped installation.

Where to go next

• Prerequisites & requirements — confirm your host and cluster qualify.
• Quick start — fastest path to a running environment.
• Configuration — the local-env.yaml reference behind the configuration model above.