Docker environment variables

Optional variables for scripts/docker/setup.sh and the gateway container, plus build memory tuning. Part of the Docker guide.

Environment variables

Optional variables accepted by scripts/docker/setup.sh (and, for the gateway container, by docker-compose.yml directly):

Variable	Purpose
`APUS_IMAGE`	Use a remote image instead of building locally
`APUS_GATEWAY_PORT`	Host-published gateway port (default `18789`); both containers keep port `18789` internally
`APUS_IMAGE_APT_PACKAGES`	Install extra apt packages during build (space-separated). Legacy alias: `APUS_DOCKER_APT_PACKAGES`
`APUS_IMAGE_PIP_PACKAGES`	Install extra Python packages during build (space-separated)
`APUS_EXTENSIONS`	Compile/package supported selected plugins and install their runtime dependencies (comma- or space-separated ids)
`APUS_DOCKER_BUILD_NODE_OPTIONS`	Override the local source-build Node options (default `--max-old-space-size=8192`)
`APUS_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB`	Override the local source-build tsdown heap in MB
`APUS_DOCKER_BUILD_SKIP_DTS`	Skip declaration output during runtime-only local image builds (default `1`)
`APUS_INSTALL_BROWSER`	Bake Chromium + Xvfb into the image at build time
`APUS_EXTRA_MOUNTS`	Extra host bind mounts (comma-separated `source:target[:opts]`)
`APUS_HOME_VOLUME`	Persist `/home/node` in a named Docker volume
`APUS_TZ`	Set the gateway and CLI container timezone to an IANA name (default `UTC`)
`APUS_SANDBOX`	Opt in to sandbox bootstrap (`1`, `true`, `yes`, `on`)
`APUS_SKIP_ONBOARDING`	Skip the interactive onboarding step (`1`, `true`, `yes`, `on`)
`APUS_DOCKER_SOCKET`	Override the Docker socket path
`APUS_DISABLE_BONJOUR`	Force Bonjour/mDNS advertising on (`0`) or off (`1`); see Bonjour / mDNS
`APUS_DISABLE_BUNDLED_SOURCE_OVERLAYS`	Disable bundled plugin source bind-mount overlays
`OTEL_EXPORTER_OTLP_ENDPOINT`	Shared OTLP/HTTP collector endpoint for OpenTelemetry export
`OTEL_EXPORTER_OTLP_*_ENDPOINT`	Signal-specific OTLP endpoints for traces, metrics, or logs
`OTEL_EXPORTER_OTLP_PROTOCOL`	Shared OTLP protocol fallback. Only `http/protobuf` is supported
`OTEL_EXPORTER_OTLP_*_PROTOCOL`	Signal-specific protocol fallback for traces, metrics, or logs; wins over the shared fallback
`OTEL_SERVICE_NAME`	Service name used for OpenTelemetry resources
`OTEL_SEMCONV_STABILITY_OPT_IN`	Opt in to latest experimental GenAI semantic attributes
`APUS_OTEL_PRELOADED`	Skip starting a second OpenTelemetry SDK when one is preloaded

After changing .env or Compose environment settings, run docker compose up -d apus-gateway to recreate the gateway with the new values. docker compose restart does not apply environment changes.

The official image ships no Homebrew. During onboarding, Apus hides brew-only skill dependency installers in a Linux container without brew; provide those dependencies through a custom image or install manually. Use APUS_IMAGE_APT_PACKAGES for Debian-packaged dependencies and APUS_IMAGE_PIP_PACKAGES for Python dependencies (runs python3 -m pip install --break-system-packages at build time, so pin versions and use only indexes you trust).

If Docker reports ResourceExhausted, cannot allocate memory, or aborts during tsdown, increase the Docker builder memory limit or retry with smaller explicit heaps:

APUS_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 APUS_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096

The explicit tsdown heap override is also the supported opt-in for attempting a build below the automatically detected safe minimum. That attempt may stall or fail.