Skip to main content

Run OctoMesh on a local kind cluster

This guide walks you through deploying OctoMesh locally using the official OctoMesh Helm charts inside a local kind (Kubernetes in Docker) cluster — the same deployment model OctoMesh uses in real clusters.

Clone the Repository​

Clone the getting-started repository to your local machine:

# Using HTTPS
git clone https://github.com/meshmakers/getting-started.git

# Using SSH
git clone git@github.com:meshmakers/getting-started.git

See Prerequisites for the tools required before installing.

Install​

cd getting-started/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).

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​

ServiceURL
Identityhttps://identity.127-0-0-1.nip.io/
GraphQL playground (system tenant)https://assets.127-0-0-1.nip.io/tenants/octosystem/graphql/playground
Bot dashboardhttps://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 managementhttp://localhost:15672/ (guest/guest)
CrateDB consolehttp://localhost:4301/
MongoDBmongodb://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.