Docker & images

HeliosLogs builds into a single small container image. This page covers running it, the volumes it needs, and building/publishing images.

The image

The provided Dockerfile is a three-stage build:

1. Build the React/Vite frontend.
2. Build the Rust backend (FIPS-enabled by default — see FIPS 140-3).
3. Assemble a distroless runtime (gcr.io/distroless/cc-debian12): glibc, CA certificates, no shell or package manager, running as a non-root user.

The default command is:

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

Build and run

make build      # docker build -t helios:latest .
make run        # run on :7300 with named volumes + admin bootstrap

make run expands to:

docker run -p 7300:7300 \
  -v helios-data:/app/data \
  -v helios-secret:/app/secret \
  -e [email protected] \
  -e HELIOS_ADMIN_PASSWORD=changeme \
  helios:latest

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: helios:latest
    ports:
      - "7300:7300"
    environment:
      HELIOS_ADMIN_EMAIL: [email protected]
      HELIOS_ADMIN_PASSWORD: changeme
      # 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.

Building and publishing multi-arch images

build-push.sh builds and pushes a multi-architecture image with Docker Buildx:

./build-push.sh v1.2.3              # build linux/amd64,linux/arm64 and push
PUSH=0 ./build-push.sh              # build both arches without pushing (validate)
IMAGE=registry.example.com/helios ./build-push.sh

Overridable via environment: IMAGE, PLATFORMS, PUSH.

Build time

The FIPS module compiles from source (Go + Perl + CMake). arm64 on Apple Silicon is quick; amd64 under QEMU emulation is slow. Build natively per-arch where you can.