Skip to main content

Online installation

The full installation walkthrough for environments where the install host and cluster can reach Docker Hub and the upstream chart repositories. For sites without internet access, see Air-gapped installation.

Before you begin​

  • Confirm prerequisites — cluster, resources, tools, Docker Hub token.
  • Have a kube context ready (kubectl config get-contexts) for the target cluster.

bin/install.sh reference​

Usage: install.sh --context <context> [OPTIONS]

Options:
    --context NAME        Kubernetes context to use (REQUIRED)
    --dry-run             Run in dry-run mode (no changes are made)
    --dump-logs           Dump logs from the install namespace to a timestamped file
    --install-cert        Install the root CA certificate into the current system
    --install-tools       Install required tools (bc, kubectl, helm, helmfile)
    --install-utils       Install utilities (k9s, stern)
    --log-level LEVEL     Log level: info (default), debug, warn, error
    -h, --help            Show help and exit

Environment Variables:
    DOCKERHUB_TOKEN       Docker Hub token required to access octostar images

--context is required. The script performs OS checks, installs prerequisites, and deploys all components via Helmfile.

Step-by-step​

1. Clone and configure​

git clone <octostar-singlenode-repository-url>
cd octostar-singlenode
cp local-env.template.yaml local-env.yaml

Edit local-env.yaml for your environment (see Configuration). At minimum, set dockerHub.token or export DOCKERHUB_TOKEN.

2. (Optional) Install tooling​

If kubectl/helm/helmfile aren't present:

./bin/install.sh --install-tools --context <context-name>
./bin/install.sh --install-utils --context <context-name>   # optional: k9s, stern

3. Run the install​

Against your cluster context:

export DOCKERHUB_TOKEN=<your-docker-hub-token>
./bin/install.sh --context <context-name>

💡 Preview first — Use --dry-run to see what would be applied without changing the cluster, and --log-level debug when you need verbose output to diagnose a problem.

4. Trust the certificate (optional)​

For the default local.test self-signed certificate:

./bin/install.sh --install-cert --context <context-name>

For production, configure a wildcard certificate or ZeroSSL in local-env.yaml instead (see Configuration).

5. Verify​

kubectl get pods -n octostar-main
kubectl get svc  -n octostar-main

When pods are Running/Ready, open https://home.<domain> (default https://home.local.test). The Fusion UI is at https://fusion.<domain> and the API at https://api.<domain>.

Targeted deployments (advanced)​

install.sh drives the full Helmfile, but you can apply individual stages directly when iterating on one service group:

helmfile -f helmfile-preps.yaml apply
helmfile -f helmfile-data.yaml apply
helmfile -f helmfile-monitoring.yaml apply
helmfile -f helmfile-octostar.yaml apply

This is primarily a development workflow — for normal installs and upgrades use install.sh / update-existing.sh so ordering and prerequisites are handled for you.

What gets deployed​

All components land in a single (configurable) namespace by default:

  • Preps — secrets, cert-manager
  • Data — ClickHouse, MySQL, OpenSearch, PostgreSQL (CNPG)
  • Object storage — SeaweedFS
  • Workflow — Temporal
  • Observability — Prometheus, Grafana, Loki (optional Tempo)
  • Core platform — octostar-api, scheduler, CDN/frontend, and the AI/ML pipeline microservices

Next steps​