Container Image

Horizon UI ships a single multi-arch container image (linux/amd64 + linux/arm64). The image bundles both the BFF and the built UI — there is no separate frontend container.

Where to get it

Registry: GitHub Container Registry (GHCR) at ghcr.io/apache/skywalking-horizon-ui.

docker pull ghcr.io/apache/skywalking-horizon-ui:0.7.0
docker pull ghcr.io/apache/skywalking-horizon-ui:<sha>

The full commit SHA is the canonical, immutable identifier. Moving tags are conveniences that point at the same SHA-built image.

Pushing a vX.Y.Z git tag publishes the :<sha> image only — that tag is a release candidate until the Apache release vote passes. The X.Y.Z, X.Y and latest tags, and the Docker Hub mirror, are attached afterwards, when the release is promoted. latest moves only if the promoted version is the highest one released, so publishing a patch on an older line never drags it backwards.

Image layout

The runtime stage runs as the non-root user horizon. /data/ is owned by horizon so the state files (audit log, wire debug log) can be written without operator intervention.

Environment variables

The two HORIZON_*_FILE env vars seed the defaults the config schema uses when horizon.yaml doesn’t supply a value. An explicit value in horizon.yaml always wins. The intent: an operator who runs the published image with only a minimal horizon.yaml (no audit/debugLog blocks) gets state files routed to /data/ automatically, no manual path overrides needed.

server.host and server.port come from the YAML when present. If they are omitted, the image supplies defaults via HORIZON_SERVER_HOST=0.0.0.0 and HORIZON_SERVER_PORT=8081. The image sets EXPOSE 8081; if you change server.port, also publish the new port.

Run with env vars only (no mounted file)

The baked /app/horizon.yaml is fully tokenized — every config field is a ${HORIZON_…:default} env var — so you can run the published image with no mounted config and set only the vars you need. Precedence is env var > the baked file’s default > built-in default. The config file itself is the complete, self-documenting list; the table below mirrors it.

Scalar vars take a plain value; list / object vars take a JSON string (injected into the YAML and parsed). A null/[] default means “use the built-in default”.

Server bind, static dir, the HORIZON_*_FILE state paths, and HORIZON_SOURCEMAPS_DIR are in the table above this section (the image already sets them to container-appropriate values).

A minimal env-only run against a real OAP with one admin user:

docker run --rm -p 8081:8081 \
  -e HORIZON_OAP_QUERY_URL=http://oap:12800 \
  -e HORIZON_OAP_ADMIN_URL=http://oap:17128 \
  -e HORIZON_AUTH_LOCAL_USERS='[{"username":"admin","passwordHash":"'"$(…cli:hash…)"'","roles":["admin"]}]' \
  ghcr.io/apache/skywalking-horizon-ui:<version>

To run standalone on the bundled templates (without Horizon’s OAP 11 /ui-management/templates* REST dependency), add -e HORIZON_TEMPLATES_MODE=readonly — dashboards render from the local bundle and the config surface is read-only (the OAP query host is still required for metrics / traces / logs). OAP 10 has its own legacy GraphQL template API, but Horizon does not consume it.

Memory & sizing

The BFF holds its source-map cache in the Node heap — uploaded Browser-Logs maps live in process memory, not in OAP — so the container’s memory limit and Node’s heap limit must be sized together with the source-map budget.

• Set NODE_OPTIONS=--max-old-space-size=<MB> to match the container memory limit (leave headroom for the rest of the process — a value somewhat below the container limit, e.g. 1536 for a 2 GiB container). --max-old-space-size is a process flag read by V8 before any config loads, so it is not a horizon.yaml field — pass it via NODE_OPTIONS (env), not in the YAML.
• Size sourceMaps.maxTotalBytes to fit comfortably inside that heap. A few recently-resolved maps are also kept parsed (larger than the raw file), so budget roughly 2× headroom above maxTotalBytes. Mounted (static) maps are disk-backed and don’t count against the heap. See Browser Logs & Source Maps.

docker run -d --name horizon \
  -p 8081:8081 \
  -e NODE_OPTIONS=--max-old-space-size=1536 \
  -v "$PWD/horizon.yaml:/app/horizon.yaml:ro" \
  ghcr.io/apache/skywalking-horizon-ui:0.7.0

How to load horizon.yaml into the container

Three common approaches.

1. Bind-mount from the host

Simplest for single-host deployments. Mount your horizon.yaml at /app/horizon.yaml:

docker run -d \
  --name horizon \
  -p 8081:8081 \
  -v "$PWD/horizon.yaml:/app/horizon.yaml:ro" \
  ghcr.io/apache/skywalking-horizon-ui:0.7.0

Notes:

• :ro — read-only mount. The BFF only reads the file; preventing writes catches mistakes.
• If your YAML sets server.host, use 0.0.0.0 in containers. 127.0.0.1 binds container loopback only, so -p 8081:8081 cannot reach it.

2. Bake it in (custom image)

For immutable single-tenant deployments, build a child image that includes your config:

FROM ghcr.io/apache/skywalking-horizon-ui:0.7.0
COPY horizon.yaml /app/horizon.yaml

Pros: one artifact contains both code and config. Cons: rebuild on every config change; secrets baked into image layers.

If you bake it in, do not include secrets directly. Use ${ENV_VAR} interpolation in the YAML (see horizon.yaml Reference) and pass the actual secrets via env at run time.

3. Kubernetes ConfigMap + Secret

Standard pattern for Kubernetes deployments. The non-secret YAML goes in a ConfigMap; secrets stay in Secret resources and are injected as env vars.

apiVersion: v1
kind: ConfigMap
metadata:
  name: horizon-config
data:
  horizon.yaml: |
    server:
      host: 0.0.0.0
      port: 8081
    oap:
      queryUrl: http://oap.skywalking:12800
      adminUrl: http://oap.skywalking:17128
      auth:
        username: skywalking
        password: "${HORIZON_OAP_PW}"
    auth:
      backend: local
      local:
        users:
          - username: admin
            passwordHash: "${HORIZON_ADMIN_HASH}"
            roles: [admin]
    rbac:
      enabled: true
    session:
      cookieSecure: true
---
apiVersion: v1
kind: Secret
metadata:
  name: horizon-secrets
type: Opaque
stringData:
  HORIZON_OAP_PW: "..."
  HORIZON_ADMIN_HASH: "$argon2id$v=19$..."
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: horizon
spec:
  replicas: 1
  selector:
    matchLabels: { app: horizon }
  template:
    metadata:
      labels: { app: horizon }
    spec:
      securityContext:
        # The image's `horizon` user is created by `adduser -S`, which
        # picks a system UID. `fsGroup` makes the mounted volumes
        # group-writable by that user without a chown sidecar.
        fsGroup: 101
      containers:
        - name: horizon
          image: ghcr.io/apache/skywalking-horizon-ui:0.7.0
          ports:
            - containerPort: 8081
          envFrom:
            - secretRef: { name: horizon-secrets }
          volumeMounts:
            - name: config
              mountPath: /app/horizon.yaml
              subPath: horizon.yaml
              readOnly: true
            - name: state
              mountPath: /data
          readinessProbe:
            httpGet: { path: /api/health, port: 8081 }
            periodSeconds: 10
      volumes:
        - name: config
          configMap:
            name: horizon-config
            items: [{ key: horizon.yaml, path: horizon.yaml }]
        - name: state
          persistentVolumeClaim:
            claimName: horizon-state

Notes:

• subPath: horizon.yaml mounts the single file rather than the directory, so it doesn’t shadow /app’s other contents.
• Mount with readOnly: true on the config — the BFF only reads it.
• /data is the image’s declared VOLUME for runtime state (audit log, wire debug). The two HORIZON_*_FILE env vars baked into the image point at /data/*, so mounting a PVC here is enough — no path overrides in horizon.yaml are required.
• fsGroup: 101 is the typical alpine nobody GID that adduser -S -G horizon horizon falls into. Run docker run --rm <image> id horizon to confirm if you’ve forked the image.
• Run a single replica unless you accept that sessions are per-pod (the in-memory session store does not federate; see session).

Persisting state files (audit, debugLog)

The BFF writes runtime state to JSON Lines files. The image declares /data as a VOLUME and points the two defaults at /data/* via env vars, so no horizon.yaml configuration is required to get writable, persistable paths — operators just mount a volume at /data:

docker run -d --name horizon \
  -p 8081:8081 \
  -v "$PWD/horizon.yaml:/app/horizon.yaml:ro" \
  -v horizon-state:/data \
  ghcr.io/apache/skywalking-horizon-ui:0.7.0

Without a mounted volume the writes still land in the container’s writable layer at /data/ (ephemeral, but at least non-failing). Mounting a volume is what makes them durable.

If you want to override the locations, you can either:

• Set the env vars: -e HORIZON_AUDIT_FILE=/var/log/horizon/audit.jsonl ..., or

• Set the paths explicitly in horizon.yaml:

  audit:    { file: /var/log/horizon/audit.jsonl }
  debugLog: { file: /var/log/horizon/wire.jsonl }
  

In either case the target directory must be writable by the horizon user. Storage classes that enforce ownership need fsGroup set in Kubernetes (or chown on bind mounts) to match the horizon UID/GID inside the container.

Where admin-edited templates live

Admin template edits (Layer-Templates, Overview-Templates, translations) are stored in OAP’s ui_template store, not inside the Horizon container — persistence follows your OAP storage backend, and nothing needs to be mounted or copied to keep them. Replacing or upgrading the Horizon container never loses admin edits.

/app/bundled_templates/ is the read-only seed source: in the default templates.mode: live, Horizon seeds any bundled template that is missing from OAP into the ui_template store at boot; in templates.mode: readonly, dashboards render directly from this bundle and the template admin surface is read-only. Nothing writes into the directory at runtime, so bind-mounting it persists nothing — mount it only if you want to replace the bundle itself (custom seed templates, or a custom read-only set for readonly mode). See horizon.yaml Reference → Template source mode.

Logging

The BFF uses pino and writes structured JSON to stdout in production — visible via docker logs <container> and ready for any log aggregator (Fluent Bit, Vector, Promtail, Filebeat, Datadog) without extra parsers.

Adjust the floor with LOG_LEVEL when triaging:

docker run -e LOG_LEVEL=info ...    # louder: add per-request access logs + lifecycle
docker run -e LOG_LEVEL=debug ...   # louder still: add the loader / capability-probe chatter
docker run -e LOG_LEVEL=trace ...   # every pino-instrumented site
docker run -e LOG_LEVEL=error ...   # quieter than the default: silences warnings
NODE_ENV=production LOG_LEVEL=info node dist/server.js

The default floor is warn (not error) because misconfiguration and security signals — break-glass logins, LDAP failures, rejected config hot-reloads — are emitted at warn, and operators are told to alert on them. Dropping to LOG_LEVEL=error silences all of those.

Per-request logging

The server request logger is on by default and emits one incoming request line + one request completed line per HTTP request, both tagged with a stable reqId. These are level-info (30) events — suppressed under the production default warn. Bump to LOG_LEVEL=info to surface them; example pair under that level:

{"level":30,"time":1779109372598,"pid":1,"hostname":"...","reqId":"req-1","req":{"method":"GET","url":"/api/auth/health","host":"127.0.0.1:8081","remoteAddress":"192.168.65.1","remotePort":60655},"msg":"incoming request"}
{"level":30,"time":1779109372614,"pid":1,"hostname":"...","reqId":"req-1","res":{"statusCode":200},"responseTime":14.93,"msg":"request completed"}

Genuine request errors (5xx, request-handler exceptions) are still logged at error (50) — they reach stdout under any default that includes error.

This is separate from the audit log (which records sensitive operations — login, rule edits, break-glass — to a JSONL file at audit.file; see Access Control → Audit Log) and the wire-debug log (which records OAP HTTP request/response payloads when debugLog.enabled: true; see Setup → debugLog). Three orthogonal channels:

Aggregating from Docker

# Quick tail with severity color (jq):
docker logs -f horizon-test | jq -c '. | "\(.time|todate) [\(.level)] \(.msg)"' -r

# Just request failures:
docker logs -f horizon-test | jq -c 'select(.res.statusCode >= 400)'

# Just structured slowness:
docker logs -f horizon-test | jq -c 'select(.responseTime != null and .responseTime > 200)'

For Kubernetes, the standard pipelines (fluent-bit tail plugin with Parser json, or vector kubernetes_logs → parse_json) ingest these lines directly. No app-side configuration required.

Network

• Container exposes 8081 by default. If you change server.port, publish the new port and update the readiness probe.
• The BFF needs egress to:
  • OAP query port (default 12800).
  • OAP admin port (default 17128).
  • OAP Zipkin port (default 9412) if any layer uses traces.source: zipkin or both.
  • LDAP server (default 636 / 389) if auth.backend: ldap.

See Network Ports for the full port matrix.

Multi-arch

The image is built for both linux/amd64 and linux/arm64. Docker auto-selects the right architecture on pull. For Apple Silicon dev hosts, the arm64 image runs natively (no emulation).

TLS

The image does not terminate TLS. Always run behind a TLS terminator (Kubernetes Ingress, Nginx, Envoy, a cloud LB). Once TLS is in front:

session:
  cookieSecure: true

so session cookies are flagged Secure and the browser refuses to send them over plain HTTP.

Building locally

The image is a multi-stage build: it compiles the app from source inside the build stage, so there is no host pre-step — docker build is self-contained (it only needs network for pnpm install during the build).

Single-arch dev build:

docker build -t horizon:local .
docker run --rm -it -p 8081:8081 \
  -v "$PWD/horizon.yaml:/app/horizon.yaml:ro" \
  horizon:local

Multi-arch build (same shape as CI — needs a docker-container buildx builder and QEMU for the non-native arch):

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t horizon:local \
  .

Health probes

Wire your platform’s readiness probe to one of:

Do not point a probe at GET /api/oap/info: it is authenticated, so an unauthenticated probe gets HTTP 401 and the pod never becomes Ready. It is an in-app, authenticated OAP-reachability indicator, not a probe target.

Liveness probes should use the public GET /api/health (or TCP-only on 8081). Wiring OAP reachability into liveness creates a cascade failure when OAP blips.

Common mistakes

• server.host: 127.0.0.1 inside the container. Listener binds loopback only; -p cannot route traffic in. Set 0.0.0.0.
• Mounting horizon.yaml as a directory. docker run -v "$PWD:/app/horizon.yaml" mounts the whole working directory and shadows /app. Always mount the file path, not the directory.
• State files lost on container replacement. The image’s defaults route state files to /data/, which is declared as a VOLUME but is ephemeral unless you bind / mount-PVC it. Mount a durable volume at /data (or override the paths via HORIZON_*_FILE env vars).
• Mounting /app/bundled_templates to “persist” admin edits. Admin template edits live in OAP’s ui_template store, not in the container — the mount persists nothing. The directory is only the read-only seed / readonly-mode source; mount it only to replace the bundle itself.
• Secrets in baked config. Use ${ENV_VAR} interpolation and pass actual secrets via env. Anything in a built image layer is recoverable by anyone who pulls the image.
• Pinning latest in production. latest moves silently; an automatic pull rolls you onto a new version without notice. Pin a SHA.
• Multi-replica without sticky sessions. Sessions are in-memory per BFF process. Multi-replica without sticky routing breaks logins on every other request.