Skip to content

Installation Guide

This page chooses a deployment model. Platform-specific pages contain the full procedure.

Prerequisites (all models)

  • 64-bit Windows or Ubuntu host
  • Reachable external MongoDB 6.0+ (the API installer does not install MongoDB)
  • A real active user ObjectID for INTEGRATION_ACTOR_USER_ID (never a generated ID)
  • Prepared configuration (.env or installer CLI flags)
  • Network path from the API host to MongoDB

Which model to use

Situation Use
Windows production Windows Native Service
Windows lab / container preference Windows Docker (source-tree installer today)
Linux production, no containers Linux Native systemd (offline prebuilt binary)
Linux production, containers required Linux Docker (offline prebuilt image) 
flowchart LR
  subgraph win [Windows]
    WN[Native]
    WD[Docker]
  end
  subgraph lin [Linux]
    LN[Native]
    LD[Docker]
  end

Honesty about package shape

Model Customer host needs Current package
Windows Native PowerShell, Administrator, Go and Git for the current installer GitHub Release *-windows-native-amd64.zip: source snapshot + existing installer. Not a prebuilt exe.
Windows Docker Docker Desktop, Linux containers, Administrator GitHub Release *-windows-docker-amd64.zip: source + docker build context. Extracted zip uses release-package mode (manifest provenance; no .git / no clone required). Not an offline image tar.
Linux Native systemd, root, sha256sum GitHub Release *-linux-native-amd64.tar.gz (offline prebuilt binary)
Linux Docker Docker Engine + Compose v2, root GitHub Release *-linux-docker-amd64.tar.gz (offline prebuilt image tar)

Do not invent a prebuilt Windows installer

The Windows zip is a checksummed source package for the existing installers. It does not remove the Go/Git (Native) or Docker Desktop / docker build (Docker) host requirements. Download and verify via Release Process.

External MongoDB

All recommended production paths use an existing MongoDB.

  • Native Windows often uses a local Windows MongoDB service (MongoDB) and can declare a service dependency.
  • Windows Docker typically uses host.docker.internal when MongoDB is on the Docker host.
  • Linux Docker production uses the operator URI as-is. Loopback inside the container is rejected. The installer does not rewrite the URI to host.docker.internal.
  • Bundled MongoDB compose is development/lab/optional legacy only.

Safe example:

text MONGODB_URI=mongodb://<MONGODB_HOST>:27017 MONGODB_DATABASE=<DATABASE_NAME> INTEGRATION_ACTOR_USER_ID=<24-hex-existing-active-user> PUBLIC_BASE_URL=http://<API_HOST>:<HOST_PORT>

Clean install checklist

  1. Confirm MongoDB is reachable from the API host.
  2. Prepare config (Windows: copy .env.example first; Linux installers can bootstrap from package example + CLI and never overwrite an existing env).
  3. Run the platform installer as Administrator / root.
  4. Confirm /health/live and /health/ready return HTTP 200.
  5. Confirm status shows the expected service/container and ports.

Next pages