a8n Systems
Sign in
Mokosh Server documentation

Running Mokosh with Docker Compose

Mokosh ships as container images you pull from Bunyip's registry and run with Docker Compose. This gets a working instance on one machine.

What you are running

  • Mokosh Server (mokosh-server) - the REST API backend, listening on port 8080. It applies its own database migrations on start.
  • PostgreSQL - the database the server uses.
  • Mokosh Web (mokosh-www) - the browser frontend. Optional for an API-only setup; see Splitting the server and web.

By default the server and web run together on one host; you can split them later.

Prerequisites

  • Docker with the Compose v2 plugin (docker compose version).
  • A Bunyip account with access, used both to sign in to the image registry and as Mokosh's single sign-on. See The image registry and signing in.

1. Sign in and pull

docker login oci.a8n.systems
docker pull oci.a8n.systems/mokosh-server:<tag>

Use the tag shown on this app's page in Bunyip, and sign in with your a8n.systems credentials.

2. A Compose file

Save the following as compose.yml. It is a minimal single-host setup; fill the CHANGE_ME and <...> placeholders. See Configuration for every variable the server accepts.

name: mokosh
services:
  server:
    image: oci.a8n.systems/mokosh-server:<tag>
    restart: unless-stopped
    environment:
      HOST: 0.0.0.0
      PORT: "8080"
      RUN_MIGRATIONS: "true"
      DATABASE_URL: postgres://mokosh:CHANGE_ME@postgres:5432/mokosh
      OIDC_ISSUER: <your Bunyip issuer, e.g. https://api.a8n.systems>
      OIDC_AUDIENCE: <the audience Mokosh accepts>
      ENCRYPTION_KEY: <32 bytes, raw or 64 hex chars>
      CORS_ORIGIN: http://localhost:8080
    ports:
      - "8080:8080"
    depends_on:
      postgres:
        condition: service_healthy
  postgres:
    image: docker.io/postgres:18-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: mokosh
      POSTGRES_PASSWORD: CHANGE_ME
      POSTGRES_DB: mokosh
    volumes:
      - mokosh-postgres:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  mokosh-postgres:

3. Start it

docker compose up -d

The server applies migrations on first start (RUN_MIGRATIONS=true) and serves the API at http://localhost:8080/api/v1/health.

Have feedback?