Skip to content

docker.md

Latest commit

 

History

History
58 lines (38 loc) · 2.32 KB

docker.md

File metadata and controls

58 lines (38 loc) · 2.32 KB
Raw

Docker Deployment

This repository now includes a Docker-first deployment path using a single container:

  • panel: the Fastify API plus the built Vue SPA
  • zero: started by the panel as a child process with manage_mode=spawn

Quick Start

  1. Put the Linux zero binary at ./runtime/zero/zero, or set ZERO_BINARY_HOST_PATH in .env.
  2. Ensure the binary matches the container architecture and is a Linux build.
  3. Start the stack:
docker compose up --build

Then open http://127.0.0.1:8080.

On startup, the container copies the mounted binary from /opt/zero-bin/zero to /usr/local/bin/zero, marks it executable, and then starts the panel. The panel creates its state under /data and writes the compiled Zero config to /etc/zero/config.json.

If the data directory has no tunnels or forwards yet, the panel seeds a bootstrap model:

  • tunnel: Bootstrap Direct
  • forward: Bootstrap Local Mixed
  • listen: 127.0.0.1:10808

This keeps the generated kernel config non-empty on first boot while remaining loopback-only by default.

Environment

The compose file wires the important runtime settings through environment variables:

  • ZERO_PANEL_HOME=/data
  • ZERO_PANEL_LISTEN=0.0.0.0:8080
  • ZERO_MANAGE_MODE=spawn
  • ZERO_AUTO_START=1
  • ZERO_BINARY=/usr/local/bin/zero
  • ZERO_CONFIG=/etc/zero/config.json
  • ZERO_CONTROL_HTTP=http://127.0.0.1:9090

These overrides are applied at runtime even when settings.json already exists, which makes container restarts predictable.

Health Model

Container health and kernel health are intentionally separated:

  • Docker healthcheck: only verifies that the panel API is responding
  • GET /api/health: returns panel status plus embedded kernel state
  • GET /api/system/kernel: returns the detailed kernel management view used by the UI

This means the container can stay healthy while the kernel is stopped or failed, which is useful for diagnosis and recovery.

Notes

  • With ZERO_AUTO_START=1, the panel compiles the current model to disk and starts the kernel during container boot. If compilation fails, the panel still starts and logs the reason.
  • If the mounted binary is missing and ZERO_MANAGE_MODE=spawn, the container exits early with a clear error.
  • The mounted binary is kept outside the image, so you can upgrade zero without rebuilding the panel image.