Run container locally

This guide walks you through setting up OctoMesh locally using Docker containers.

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

Prerequisites

Before you begin, ensure you have the following installed:

Requirement	Version	Installation
Docker Desktop	4.29+	docker.com
PowerShell	7.1+	Microsoft Docs
OpenSSL	-	winget install -e --id ShiningLight.OpenSSL (Windows) or brew install openssl (macOS)
octo-cli	-	choco install octo-cli or winget install meshmakers.octo-cli

Verify the prerequisites are installed:

openssl version
docker --version
octo-cli

Configure Hosts File

Edit the hosts file as administrator and add the following entry:

• Windows: C:\Windows\System32\drivers\etc\hosts
• Linux/macOS: /etc/hosts

# OctoMesh Identity Services
127.0.0.1 octo-identity-services
# end OctoMesh Identity Services

Scripts Overview

The scripts/ folder contains PowerShell scripts to manage the OctoMesh platform:

Script	Description
om-install.ps1	Installs and configures OctoMesh. Prompts for version selection and license keys, creates SSL certificates, starts Docker containers, and initializes the MongoDB replica set.
om-start.ps1	Starts the OctoMesh Docker containers after they have been stopped.
om-stop.ps1	Stops all running OctoMesh Docker containers without removing data.
om-uninstall.ps1	Completely removes the OctoMesh platform including all Docker containers and volumes.
om-login-local.ps1	Configures octo-cli for the local environment and initiates an interactive login. Supports -tenantId and -includeReporting parameters.
om-setupIdentityService-local.ps1	Creates Identity Service client definitions for Data Refinery Studio. Required when using the full profile.

Deployment Profiles

The scripts om-install.ps1, om-start.ps1, and om-stop.ps1 support a -DeploymentProfile parameter:

Profile	Description
core	Default. Starts all services except Data Refinery Studio.
full	Starts all services including Data Refinery Studio.

Install OctoMesh

Navigate to the scripts directory and run the installation script:

cd getting-started/scripts

# Install with core profile (default)
./om-install.ps1

# Install with full profile (includes Data Refinery Studio)
./om-install.ps1 -DeploymentProfile full

The installation script will:

1. Check prerequisites - Verifies Docker, OpenSSL, and octo-cli are available
2. Select version - Prompts you to select an OctoMesh version from available releases
3. Enter license keys - Prompts for required license keys:
   • Identity Server License Key - Get from Duende Software (Community edition is free for small companies and open source projects)
   • AutoMapper License Key - Get from AutoMapper (Free tier available)
4. Create certificates - Generates SSL certificates for HTTPS
5. Start containers - Launches all OctoMesh services via Docker Compose
6. Initialize database - Sets up the MongoDB replica set

Install the Certificate

After installation, the SSL certificate is created in getting-started/scripts/octo-mesh/localhost_cert.pfx.

Windows:

1. Double-click the .pfx file
2. Select "Local Machine" and click Next
3. Click Next on the file path screen
4. Enter password: Secret01
5. Select "Place all certificates in the following store"
6. Click Browse and select "Trusted Root Certification Authorities"
7. Complete the wizard

macOS:

1. Double-click the .pfx file to add to Keychain
2. Enter password: Secret01
3. Open Keychain Access
4. Find the certificate and double-click it
5. Expand "Trust" and set "When using this certificate" to "Always Trust"

Create Admin User

1. Navigate to https://octo-identity-services:5003/ in your browser
2. Register the admin user with an email and password

note

The email must be in a valid format but does not need to be a real email address.

Log-In to octo-cli

Run the following command to configure and log in to octo-cli:

# Default login (tenant: meshtest, no reporting)
./om-login-local.ps1

# Custom tenant ID
./om-login-local.ps1 -tenantId "mytenant"

# Include Reporting Services (for full profile)
./om-login-local.ps1 -includeReporting $true

# Both parameters
./om-login-local.ps1 -tenantId "mytenant" -includeReporting $true

Parameter	Default	Description
-tenantId	meshtest	The tenant ID to configure for the CLI.
-includeReporting	$false	Set to $true to include Reporting Services URL.

Setup Identity Service (Full Profile Only)

If you installed with -DeploymentProfile full, run the following command after logging in to setup the client definitions for Data Refinery Studio:

./om-setupIdentityService-local.ps1

This script registers the Data Refinery Studio client with the Identity Service and assigns the required API scopes.

Available Services

Service	URL
OctoMesh Identity Services	https://octo-identity-services:5003/
OctoMesh GraphQL Playground	https://localhost:5001/tenants/octosystem/graphql/playground
OctoMesh Admin Panel	https://localhost:5005/
OctoMesh Data Refinery Studio	https://localhost:5011/ (full profile only)
OctoMesh Bot Dashboard	https://localhost:5009/ui/jobs

Managing the Platform

Stop OctoMesh (keeps data):

# Stop core profile
./om-stop.ps1

# Stop full profile
./om-stop.ps1 -DeploymentProfile full

Start OctoMesh (after stop):

# Start core profile
./om-start.ps1

# Start full profile
./om-start.ps1 -DeploymentProfile full

Uninstall OctoMesh (removes all data):

./om-uninstall.ps1