6 min read·Updated 2026-04-10

Deployment

Deploy with Docker, Compose, or JAR. Recommended default: Docker. Production checklist covers persistence, auth, TLS, backups, and health.

Three packaging choices

The runtime ships as a Docker image, a Docker Compose skeleton, and a standalone JAR. Pick one — they are three packaging choices around the same process.

Compare the three

Docker

Best default for portable, repeatable deployment. One command, one volume, runs everywhere Docker runs.

Recommended

Docker Compose

Use when you also need sidecars (LightRAG, Hive, external databases). Keeps multi-container orchestration in one file.

Multi-service

JAR

Use for host-level development, controlled Java service deployment, or environments where you cannot run Docker.

Direct

If you do not yet know which you need, use Docker. One command, one volume, one port. Switch to Compose only when you add a second container (LightRAG, Hive). Use the JAR only when Docker is off the table.

Docker Compose skeleton

docker-compose.yml skeleton

yaml

services:
  golemcore-bot:
    image: ghcr.io/alexk-dev/golemcore-bot:latest
    restart: unless-stopped
    shm_size: 256m
    cap_add:
      - SYS_ADMIN
    environment:
      STORAGE_PATH: /app/workspace
      TOOLS_WORKSPACE: /app/sandbox
    volumes:
      - ./workspace:/app/workspace
      - ./sandbox:/app/sandbox
    ports:
      - "8080:8080"

Bring it up

bash

docker compose up -d

Example output

text

[+] Running 2/2
 ✔ Network golemcore_default           Created  0.1s
 ✔ Container golemcore-golemcore-bot-1 Started  0.3s

Production checklist

Before you call a deployment production-ready, verify each item. Every one has bitten real operators; none are optional.

Persistent volumes mounted. workspace and sandbox are on a named volume or host mount. Verify with docker inspect golemcore-bot.
Admin password rotated. The initial password from the logs is replaced via Settings → Security, or BOT_DASHBOARD_ADMIN_PASSWORD is set at container start.
Provider key stored in the config, not in the image. Keys are in preferences/llm-providers.json on the persistent volume, never baked into the image.
Model router assignments populated. At least balancedModel is set in preferences/model-router.json.
Browser flags set if you use the browser plugin. --shm-size=256m and --cap-add=SYS_ADMIN are present. Without them, Chromium crashes silently.
Dashboard reachable behind TLS. Do not expose port 8080 directly on a public interface. Front it with a reverse proxy that terminates TLS.
Backups of the workspace volume. Volume snapshot schedule or file-level backup of workspace/.
Logs collected. docker logs is tailed into your log aggregator, or workspace/logs/ is read directly.
Health endpoint monitored. /actuator/health is polled by your monitoring system.

What to do next

Configuration

Understand the configuration layers before you customize the JSON files the deployment depends on.

Concept

Troubleshooting

Symptom-to-fix lookup for common deployment problems.

Reference

User Guide

Configuration

How configuration is layered across workspace storage, runtime sections, and user preferences. The dashboard edits most of it.

User Guide

Quickstart

Install the runtime with one Docker command, open the dashboard, add a provider, and send a first message.