Getting started with OctoMesh

This repository deploys the OctoMesh platform on your machine using the official OctoMesh Helm charts inside a local kind (Kubernetes in Docker) cluster — the same deployment model OctoMesh uses in real clusters.

Prerequisites

• Docker Desktop (or Docker Engine on Linux)
  • Note: images are multi-arch (amd64/arm64) as of release 3.4.51; Apple Silicon works natively. Releases older than 3.4.51 are amd64-only.
• PowerShell 7.4+
• kind v0.31+ (brew install kind / winget install Kubernetes.kind)
• kubectl
• helm v3
• openssl in PATH (brew install openssl / winget install ShiningLight.OpenSSL.Dev)
• octo-cli (choco install octo-cli on Windows; download the self-contained binary for macOS/Linux from the Download Center) — minimum version 3.4.51
• License keys (both prompted during installation):
  • Duende IdentityServer — community edition is free for small companies and open source
  • AutoMapper — free tier available

No hosts-file entry and no manual certificate import are needed: services are reached at *.127-0-0-1.nip.io hostnames (public DNS that resolves to 127.0.0.1) and the installer sets up a locally-trusted certificate authority.

Install

cd scripts
./om-install.ps1                          # core profile
./om-install.ps1 -DeploymentProfile full  # + Refinery Studio and Reporting

The installer:

1. creates a kind cluster named octomesh (all ports bound to 127.0.0.1 only),
2. installs MongoDB, RabbitMQ, and CrateDB,
3. installs ingress-nginx and cert-manager with a local root CA (you will be asked for sudo/admin rights to trust it; skip with -SkipTrustCa),
4. installs the OctoMesh platform and the Communication Operator from the public Helm chart repository (release versions only — you pick the version, latest is the default). Companion chart versions (mesh adapter, simulation, reporting) are resolved automatically to the newest release compatible with the chosen platform version, since those repos release independently.

Create the admin user and log in

1. Open https://identity.127-0-0-1.nip.io/ and register the admin user (the email address must be well-formed but does not need to exist).
2. Configure and log in the CLI:

./om-login-local.ps1                          # tenant: meshtest
./om-login-local.ps1 -tenantId "mytenant"     # custom tenant
./om-login-local.ps1 -includeReporting $true  # full profile

Create a tenant and deploy the mesh adapter

./om-bootstrap-tenant.ps1                       # tenant meshtest + mesh adapter
./om-bootstrap-tenant.ps1 -IncludeSimulation    # + simulation adapter

This creates the tenant, enables communication (which seeds the default pool, the mesh adapter, and the public chart repository), and deploys the adapters through the Communication Operator — exactly the way managed OctoMesh environments work.

URLs

Service	URL
Identity	https://identity.127-0-0-1.nip.io/
GraphQL playground (system tenant)	https://assets.127-0-0-1.nip.io/tenants/octosystem/graphql/playground
Bot dashboard	https://bots.127-0-0-1.nip.io/ui/jobs
Platform services (configuration discovery)	https://platform.127-0-0-1.nip.io/octosystem/_configuration
Refinery Studio (full profile)	https://studio.127-0-0-1.nip.io/
Reporting (full profile)	https://reporting.127-0-0-1.nip.io/
RabbitMQ management	http://localhost:15672/ (guest/guest)
CrateDB console	http://localhost:4301/
MongoDB	mongodb://localhost:27017

Manage the installation

./om-status.ps1      # pods, helm releases, ports, URLs
./om-stop.ps1        # stop the cluster (data preserved)
./om-start.ps1       # start it again (waits for Identity, then restarts dependent services once)
./om-uninstall.ps1   # delete the cluster AND ALL DATA, untrust the CA
                     # (keeps local-config.json with the selected version + license keys)

Troubleshooting

• *.127-0-0-1.nip.io does not resolve — some routers/corporate DNS servers block DNS answers that point to 127.0.0.1 (rebind protection). Fallback: add 127.0.0.1 identity.127-0-0-1.nip.io assets.127-0-0-1.nip.io bots.127-0-0-1.nip.io communication.127-0-0-1.nip.io platform.127-0-0-1.nip.io studio.127-0-0-1.nip.io reporting.127-0-0-1.nip.io to your hosts file.
• Docker Hub rate limits during install — anonymous pulls are limited; run docker login with a free Docker account before installing.
• Ports already in use — the installer refuses when 80/443/27017/5672/15672/5432/4301 are taken (e.g. by another local database). Stop the conflicting service first.
• Browser warns about the certificate — the root CA trust step was skipped or failed. Re-run ./om-install.ps1 without -SkipTrustCa, or trust scripts/kubernetes/.generated/local-root-ca.crt manually.
• After a cluster cold start, API calls fail with 401 — services that boot while Identity is not yet reachable cache a broken OIDC metadata state and then reject valid tokens until their pods are restarted (the state does not self-heal). om-start.ps1 handles this automatically: after a cold start it waits for Identity's JWKS and then restarts the token-validating services once. If you still see 401s (e.g. after restarting the Docker VM without om-start.ps1), run the remedy manually (omit octo-mesh-reporting on the core profile): kubectl --context kind-octomesh -n octo rollout restart deployment octo-mesh-asset-rep-services octo-mesh-bot-services octo-mesh-communication-controller-services octo-mesh-platform-services octo-mesh-reporting

Further reading

• OctoMesh documentation