Skip to main content

Configuration

All deployment configuration lives in local-env.yaml, created by copying local-env.template.yaml. This page is the operator reference for the settings that matter most at install time.

The three-tier model​

Values resolve in order, each overriding the previous:

  1. defaults.yaml — safe base defaults. Do not edit.
  2. versions.yaml — pinned component and image versions.
  3. local-env.yaml — your overrides. The only file you normally edit.
cp local-env.template.yaml local-env.yaml

Everything in the template is commented out and shows the corresponding default, so you only uncomment what you intend to change.

💡 Generate it interactively — Rather than hand-editing, you can run ./bin/setup-local-env.sh, which prompts for namespace, domains, and which optional components to enable (MetalLB, ingress, cert-manager, monitoring, ClickHouse, PostgreSQL, OpenSearch, SeaweedFS) and writes local-env.yaml for you. See Air-gapped installation §3 — the same script is used online.

Essential settings​

Docker Hub access​

dockerHub:
  token: "your-docker-hub-token"   # required for online installs
  # server: "https://index.docker.io/v1/"   # try this if image pulls fail
  # username: octostar

Alternatively export DOCKERHUB_TOKEN in the environment. Not needed for air-gapped installs (which use a private registry).

Domain and certificates​

octostar:
  domain: "local.test"      # leave as local.test for self-signed local DNS,
                            # or set to e.g. "os.example.com" for production
  internalDomain: true      # inject a self-signed cert when the domain isn't public
  backendReplicaCount: 4

With a custom domain, point home.<domain>, fusion.<domain>, and api.<domain> at this host in DNS. For publicly trusted certificates use ZeroSSL or a wildcard certificate (below).

Namespace​

# namespace: "octostar-main"   # default; everything deploys here

Dataset size​

# bigData: "none"   # "small" ≈ 30 GB free space, "large" ≈ 100 GB

Certificates​

Choose one approach:

ApproachWhen to useKeys
Self-signed (default)local.test / internal demosoctostar.internalDomain: true
Supplied TLS secretYou already have a cert/key (PEM, base64)tls.cert, tls.key
Wildcard certificateOne cert for *.<domain>wildcard.enabled, wildcard.cert, wildcard.key
ZeroSSL (ACME)Automatic public certszeroSsl.eab.keyId, zeroSsl.eab.hmac, zeroSsl.challengeType (http01 default / dns01), zeroSsl.email, zeroSsl.cloudflareApiToken (for dns01)

Data and storage backends​

PostgreSQL (CloudNativePG)​

postgresql:
  username: octostar
  password: ""        # empty → random password generated on first install
  replicas: 1
  cpu: 2              # integer ≥ 1
  memoryGb: 8         # integer ≥ 5
  storageClass: ""    # empty → cluster default
  storageSize: ""     # e.g. "50Gi"

For air-gap, also set imageName, operatorImageRepository, and operatorImageTag to your mirrored images — see Air-gapped installation.

ClickHouse​

clickhouse:
  enabled: true
  replicas: 1
  username: clickhouse_admin
  password: ""            # empty → random password at install time
  storage:
    size: 150G
  settings:
    max_server_memory_usage_to_ram_ratio: 0.5
  grafana:
    password: "..."       # read-only access from Grafana

Set enabled: false to use an existing external ClickHouse.

OpenSearch​

opensearch:
  enabled: true
  replicas: 1              # WARNING: lowering this can cause data loss
  username: "admin"        # applied only at install time
  password: "..."          # applied only at install time
  memoryGb: 6              # ≥ 5 and > heapGb
  heapGb: 4                # 4–30
  # url / port:            # set ONLY to point at an external OpenSearch

Object storage — SeaweedFS​

SeaweedFS is the S3-compatible object store used by the platform (octostar-api, langfuse, …):

seaweedfs:
  enabled: true
  active: true
  volume:
    replicas: 3
    storageSize: "50Gi"
    storageClass: ""
  master:
    defaultReplication: "001"   # "001" = 2 copies across servers; "000" = none (single-node/dev)
  # s3.accessKeyId / s3.secretAccessKey are managed automatically by the
  # octostar-k8s-prep job (accessKeyId defaults to "seaweedfs", secret is
  # generated on first install). Override only if you need a known key pair.

Networking​

ingress:
  enabled: true
  className: nginx-octostar           # use "nginx" on a local single-node cluster
  namespace: ingress-nginx-octostar   # use "ingress-nginx" on a local single-node cluster
  service:
    type: NodePort

metallb:
  enabled: false
  address: "10.96.0.2/32"

certManager:
  enabled: true
  namespace: cert-manager

Monitoring​

monitoring:
  namespace: "octostar-main"
  loki:
    retentionPeriod: "7d"
    maxEntriesLimitPerQuery: 10000
  tempo:
    enabled: false        # distributed tracing
    retentionPeriod: "24h"

Platform behaviour and branding​

Under the octostar: block:

KeyPurpose
deployApps"true" to auto-deploy workspace UI apps via AppLifecycle
appsListPipe-separated list of workspace UI apps to deploy (e.g. EntityExtract&Graph | ReportCreator | DataLab | …)
appParallelDeploysNumber of apps deployed in parallel
extraWorkspaces"all" (default), "" (core only), or "a, b, c" (core + listed)
mainLogo / favicon / spinnerBranding — HTTPS URL or data:image/...;base64,...
ecPrivKey / jwtKey64-hex-char secrets; set "" to auto-generate
session.idleTimeoutSecondsIdle timeout (default 3600, min 300)
session.maxSessionSecondsAbsolute session cap (default 864000, min 600)

Other components​

  • Fusion center (timbr) — timbr.license, timbr.serverMemoryGb (≥ 5,

    heap), timbr.serverHeapGb (4–30).

  • Temporal — temporal.*, temporalWorker.*.
  • vLLM — vllm.enabled, vllm.url, vllm.model_name.
  • Tile server / Photon geocoding — large optional geodata stacks (≈ 200 GB / ≈ 300 GB); see the template comments.
  • Pipeline components — objectDetection, dataCutter, documentExtractor, imageAugmentation, audioTranscription. Each exposes worker queues, per-task time limits, dynamic batching, and CPU/GPU model placement. Leave commented to use chart defaults; for GPU tuning start from local-env.template-gpu.yaml (see GPU deployments).
  • API keys — assemblyAIAPIKey, espysysAPIKey, openaiToken, socialGistAPIKey, socialLinksAPIKey, localLLMLicenseKey, plus the langfuse: block (several langfuse secrets are write-once at install time — note the inline # write-once markers in the template).

Write-once secrets​

⚠️ Warning — Several values (notably langfuse salt, encryptionKey, project keys) are applied only on first install and cannot be changed later by editing local-env.yaml. Decide on these before your first install.