Skip to main content
Version: 3.0

Install and run

Get started takes the shortest way in. This page has every way to install MaestroHub, and what you may need once it runs.

Install​

MaestroHub runs as a single binary or Docker container. No external databases, no message brokers: everything is embedded.

Download from the MaestroHub Portal and run:

  1. Download the ZIP file and extract it

After extraction, you'll see the following structure:

context-platform_3.0.0_windows_amd64/
├── README.txt
├── ThirdPartyNotices.txt
├── starter.bat
├── context-platform.exe
├── admin-cli.exe
└── config.yaml
  1. Double-click starter.bat (or run context-platform.exe directly)

The browser opens automatically at http://localhost:6163.

Configuration​

Customize MaestroHub by editing config.yaml:

http:
  port: 8080

Or use environment variables with the MAESTROHUB_ prefix:

export MAESTROHUB_HTTP_PORT=8080

Restart the application after changes.

HTTPS​

MaestroHub serves the UI and API over HTTPS on a second port when you give it a certificate:

http:
  port: 8080            # plain HTTP stays: health checks use it
  tls:
    certFile: /etc/maestrohub/tls/tls.crt   # PEM chain, leaf first
    keyFile: /etc/maestrohub/tls/tls.key
    port: 8443          # default

The environment variables are MAESTROHUB_HTTP_TLS_CERTFILE, MAESTROHUB_HTTP_TLS_KEYFILE and MAESTROHUB_HTTP_TLS_PORT.

  • The certificate must name every address people use to open MaestroHub (its DNS names, or IP addresses).
  • MaestroHub reads the files again when they change, so a renewed certificate is served without a restart. If the new files don't form a valid pair, it keeps serving the previous certificate and logs a warning.
  • The live data in the UI uses a WebSocket on the same origin, so it is encrypted (wss://) too.
  • Expose only the HTTPS port where traffic crosses a network. Plain HTTP on 8080 is for health checks and local callers.

With Docker, mount the files and publish the HTTPS port:

docker run -d \
  --name maestrohub \
  -p 8443:8443 \
  -v maestrohub-data:/data \
  -v /srv/maestrohub/tls:/etc/maestrohub/tls:ro \
  -e MAESTROHUB_HTTP_TLS_CERTFILE=/etc/maestrohub/tls/tls.crt \
  -e MAESTROHUB_HTTP_TLS_KEYFILE=/etc/maestrohub/tls/tls.key \
  maestrohub/context-platform:3.0.0

The embedded MQTT broker can serve TLS from the same files: see UNS settings › TLS. MQTT TLS is optional, so a demo or trial works without a certificate, but devices' passwords and values then cross the network in the clear: use TLS in production. The broker logs a warning at every start while it serves plain MQTT only, and the MQTT Broker page shows it under Encryption. On Kubernetes, the single-node Helm chart sets all of this up from one Secret (tls.enabled, tls.secretName).

Docker lifecycle commands​

# View logs
docker logs -f maestrohub        # or: docker-compose logs -f

# Stop (data preserved)
docker stop maestrohub            # or: docker-compose stop

# Start again
docker start maestrohub           # or: docker-compose start

# Health check
curl http://localhost:8080/health

# Full reset
docker stop maestrohub && docker rm maestrohub
docker volume rm maestrohub-data

Troubleshooting​

  • Port in use: Check lsof -i :6163 (binary) or lsof -i :8080 (Docker)
  • macOS security block: System Settings > Privacy & Security > Open Anyway
  • Clean restart: Delete ~/maestrohub/data/ (binary) or remove Docker volume
  • Container not starting: Check docker logs maestrohub

Encryption keys and runtime secrets​

MaestroHub uses several runtime secrets: JWT signing keys, the OAuth2 client secret, and encryption keys for the Connectors and UNS databases. They are persisted under a secrets/ subfolder of your MaestroHub data directory (mode 0600):

secrets/
├── auth_jwt_access_secret
├── auth_jwt_refresh_secret
├── auth_jwt_password_reset_secret
├── oauth2_secret
├── connectors_encryption_key
└── uns_encryption_key
InstallWhere the secrets/ folder lives
Binary~/maestrohub/data/secrets/ (i.e. inside $HOME/maestrohub/data/, alongside the SQLite database files)
Dockerinside the volume you mounted at /data (full path /data/data/secrets/ from inside the container)

Once a file exists in this directory, MaestroHub uses its contents as-is: keys never silently rotate underneath the data they protect.

Bring your own keys. Two ways, in order of precedence:

  1. Environment variables. Set the value before the first boot (or before you next restart). Useful for Docker / orchestrators.

    VariablePurpose
    MAESTROHUB_MODULES_AUTH_JWT_ACCESSSECRETJWT access-token signing key
    MAESTROHUB_MODULES_AUTH_JWT_REFRESHSECRETJWT refresh-token signing key
    MAESTROHUB_MODULES_AUTH_JWT_PASSWORDRESETSECRETPassword-reset token signing key
    MAESTROHUB_MODULES_OAUTH2_SECRETOAuth2 client secret
    MAESTROHUB_MODULES_CONNECTORS_ENCRYPTIONKEYAES key for connector secrets
    MAESTROHUB_MODULES_UNS_ENCRYPTIONKEYAES key for UNS settings secrets

  2. Pre-seed the secrets file. Write your value to data/secrets/<file> (mode 0600) before first boot. The runtime sees the file and uses it as-is.

Connector and UNS encryption keys must be 16, 24, or 32 bytes (AES-128 / 192 / 256). They can be supplied as raw bytes (ASCII) or as a base64-encoded string.

Rotating an encryption key. To rotate the Connectors or UNS encryption key against existing data, use admin-cli reencrypt. It re-wraps every encrypted row under the new key and updates the secrets file atomically.