qubiccore/lite repository overview

⁠Qubic Core Lite

Run a Qubic network node in Docker with automatic snapshot downloads, health monitoring, and self-healing restarts.

⁠Quick Start

docker run -d --name qubic-node \
  -p 21841:21841 \
  -p 41841:41841 \
  -v qubic-data:/qubic \
  qubiccore/lite:latest

Or with Docker Compose:

services:
  qubic-node:
    image: qubiccore/lite:latest
    restart: unless-stopped
    ports:
      - "21841:21841"   # P2P
      - "41841:41841"   # HTTP API
    volumes:
      - qubic-data:/qubic

  # use watchtower to enable auto update of core lite
  watchtower:
    image: containrrr/watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      WATCHTOWER_POLL_INTERVAL: 60
      DOCKER_API_VERSION: "1.44"
    command: qubic-node


volumes:
  qubic-data:

⁠What It Does

On startup the orchestrator:

1. Discovers the current epoch from the Qubic network API
2. Downloads the latest snapshot (or epoch files) if local state is missing or outdated
3. Starts the Qubic node with the configured parameters
4. Monitors health via a built-in watchdog that detects crashes, stuck ticks, and consensus misalignment
5. Automatically restarts the node when problems are detected

⁠Ports

⁠Environment Variables

⁠General

⁠Operator (optional)

⁠Watchdog

⁠Alerting (optional)

⁠Container Commands

The built-in orchestrator-ctl CLI lets you manage the node via docker exec:

# Check node status (epoch, tick, health, peers)
docker exec qubic-node orchestrator-ctl status

# Quick health check
docker exec qubic-node orchestrator-ctl health

# Restart the Qubic node binary
docker exec qubic-node orchestrator-ctl restart

# Send a key command to the Qubic process
docker exec qubic-node orchestrator-ctl send-key f4

# List all available key commands
docker exec qubic-node orchestrator-ctl keys

⁠Available Key Commands

⁠Management API

The orchestrator also exposes a local HTTP API on port 8080 (localhost only by default).

# Health check
curl http://localhost:8080/health

# Detailed node status (epoch, tick, health, votes)
curl http://localhost:8080/status

# Manually restart the node
curl -X POST http://localhost:8080/restart

# Send a key command to the Qubic process
curl -X POST -d '{"key":"f4"}' http://localhost:8080/send-key

# List available key commands
curl http://localhost:8080/keys

⁠Watchdog

The built-in watchdog monitors the node and automatically restarts it when:

• Crash detected — the Qubic process exits unexpectedly
• Stuck — no tick progression for 5 minutes (configurable)
• Misaligned — consensus misalignment detected over consecutive polls

The watchdog respects a startup grace period (5 minutes), enforces cooldown between restarts, and stops after reaching the max restart limit to prevent infinite loops. All restart events are logged and optionally sent as webhook alerts.

⁠Alerting

Configure a webhook URL to receive alerts for node events:

• Node crashes, restarts, and recovery
• Stuck or misaligned state detection
• Epoch transitions
• Max restarts exceeded (requires manual intervention)

Alerts include node context (epoch, tick, health state, restart count) and are rate-limited to prevent flooding.

docker run -d --name qubic-node \
  -p 21841:21841 \
  -v qubic-data:/qubic \
  -e QUBIC_ALERTING__ENABLED=true \
  -e QUBIC_ALERTING__WEBHOOK_URL="https://hooks.slack.com/services/..." \
  qubiccore/lite:latest

⁠Data Persistence

Mount a volume to /qubic to persist node state across container restarts:

-v qubic-data:/qubic

This directory contains epoch state files (spectrum, universe, contracts), snapshot data, and node configuration. Without a persistent volume, the node will re-download all state on every container restart.

⁠Health Check

The image includes a Docker health check that queries the node's HTTP API every 30 seconds with a 5-minute startup grace period. Use docker inspect or your orchestration platform to monitor container health.

⁠Requirements

• CPU: x86_64 (AVX2 support recommended)
• RAM: 64GB minimum for mainnet
• Disk: 50GB+ for state files
• Network: Stable connection with port 21841 accessible for P2P

⁠Links

• Source Code⁠