Docker & images

HeliosLogs ships as a single small container image on Docker Hub. This page covers pulling it, running it, and the volumes it needs.

The image

Published on Docker Hub as helioslogs/helioslogs, in two flavors:

Tag	Build
helioslogs/helioslogs:latest	Standard build.
helioslogs/helioslogs:latest-fips	FIPS 140-3 build — AWS-LC validated module. See FIPS 140-3.

Each is a distroless runtime (gcr.io/distroless/cc-debian12): glibc, CA certificates, no shell or package manager, running as a non-root user. The built frontend is baked in.

The default command is:

serve --host 0.0.0.0 --port 7300 --data-dir /app/data --frontend-dir /app/frontend/dist

Pull and run

docker pull helioslogs/helioslogs:latest

docker run -p 7300:7300 \
  -v helios-data:/app/data \
  -v helios-secret:/app/secret \
  helioslogs/helioslogs:latest

For the FIPS build, swap in helioslogs/helioslogs:latest-fips.

Receiving syslog

To accept raw syslog (UDP + TCP on 5514), add -p 5514:5514/udp -p 5514:5514/tcp to the run command. The listener is off by default — enable it under Admin → Data Ingestion → Syslog. See Syslog.

Volumes

The image declares two volumes, and they serve different purposes:

Mount	Holds	Notes
/app/data	Block partitions and (single-node) control plane	A per-node cache when a shared store is used — can be wiped and rebuilt.
/app/secret	secret-control.json and secret-jwt.json	Persistent and precious. The image pre-points the key paths here.

The image sets these by default so keys never land in the data cache:

HELIOS_CONTROL_KEY_PATH=/app/secret/secret-control.json
HELIOS_JWT_SECRET_PATH=/app/secret/secret-jwt.json

Back up the secret volume

Losing secret-control.json means the encrypted control plane can never be decrypted again — users, settings, dashboards, and monitors are gone. Treat /app/secret like a database backup. See Secrets & encryption.

docker-compose

A single-node example with persistent volumes:

services:
  helios:
    image: helioslogs/helioslogs:latest
    ports:
      - "7300:7300"
      # Raw syslog (off by default — enable in Admin → Data Ingestion → Syslog):
      # - "5514:5514/udp"
      # - "5514:5514/tcp"
    environment:
      # Optional: shared store on S3
      # AWS_REGION: us-east-1
    command:
      - serve
      - --host=0.0.0.0
      - --port=7300
      - --data-dir=/app/data
      - --frontend-dir=/app/frontend/dist
      # - --shared-store=s3://my-bucket/helios
    volumes:
      - helios-data:/app/data
      - helios-secret:/app/secret

volumes:
  helios-data:
  helios-secret:

For S3-backed multi-node, mount the same secret files on every node and pass --shared-store. See Multi-node & shared store.