Docker quick start

Pre-built images are published to GitHub Container Registry, for example:

ghcr.io/hyperbyte-cloud/hyperbytedb:latest

The container listens on 8086 for the InfluxDB v1–compatible HTTP API (/write, /query, /health, …) and for Prometheus metrics at GET /metrics on the same port—publish 8086 once; there is no separate metrics port. Persist data on a volume; the image defaults storage paths under /var/lib/chinflux.

---

Single node

Pull and run:

docker pull ghcr.io/hyperbyte-cloud/hyperbytedb:latest

docker run -d \
  --name hyperbytedb \
  -p 8086:8086 \
  -v hyperbytedb-data:/var/lib/chinflux \
  -e CHINFLUX__SERVER__BIND_ADDRESS=0.0.0.0 \
  -e CHINFLUX__SERVER__PORT=8086 \
  ghcr.io/hyperbyte-cloud/hyperbytedb:latest

Check health and Prometheus metrics (same port 8086):

curl -sSf http://localhost:8086/health
curl -sSf http://localhost:8086/metrics | head

Optional smoke test — create a database, then write line protocol:

curl -sS -G 'http://localhost:8086/query' --data-urlencode 'q=CREATE DATABASE mydb'

curl -sS -X POST 'http://localhost:8086/write?db=mydb' \
  --data-raw 'cpu,host=server1 value=42'

CHINFLUX__SERVER__BIND_ADDRESS=0.0.0.0 is required so the process accepts connections from outside the container.

---

Cluster (Docker Compose)

Each node needs:

• CHINFLUX__CLUSTER__ENABLED=true
• A unique CHINFLUX__CLUSTER__NODE_ID
• CHINFLUX__CLUSTER__CLUSTER_ADDR set to this container’s address as seen by other nodes (on a user-defined network, use the Compose service name and port 8086)
• CHINFLUX__CLUSTER__PEERS as a comma-separated list of the other nodes’ cluster addresses (do not include yourself)

Use fixed hostnames (service names) and persist cluster state under /var/lib/chinflux, including the replication log:

services:
  db1:
    image: ghcr.io/hyperbyte-cloud/hyperbytedb:latest
    hostname: db1
    ports:
      - "8086:8086"
    volumes:
      - db1-data:/var/lib/chinflux
    environment:
      CHINFLUX__SERVER__BIND_ADDRESS: "0.0.0.0"
      CHINFLUX__SERVER__PORT: "8086"
      CHINFLUX__CLUSTER__ENABLED: "true"
      CHINFLUX__CLUSTER__NODE_ID: "1"
      CHINFLUX__CLUSTER__CLUSTER_ADDR: "db1:8086"
      CHINFLUX__CLUSTER__PEERS: "db2:8086,db3:8086"
      CHINFLUX__CLUSTER__REPLICATION_LOG_DIR: "/var/lib/chinflux/replication_log"
    networks:
      - cluster

  db2:
    image: ghcr.io/hyperbyte-cloud/hyperbytedb:latest
    hostname: db2
    ports:
      - "8087:8086"
    volumes:
      - db2-data:/var/lib/chinflux
    environment:
      CHINFLUX__SERVER__BIND_ADDRESS: "0.0.0.0"
      CHINFLUX__SERVER__PORT: "8086"
      CHINFLUX__CLUSTER__ENABLED: "true"
      CHINFLUX__CLUSTER__NODE_ID: "2"
      CHINFLUX__CLUSTER__CLUSTER_ADDR: "db2:8086"
      CHINFLUX__CLUSTER__PEERS: "db1:8086,db3:8086"
      CHINFLUX__CLUSTER__REPLICATION_LOG_DIR: "/var/lib/chinflux/replication_log"
    networks:
      - cluster

  db3:
    image: ghcr.io/hyperbyte-cloud/hyperbytedb:latest
    hostname: db3
    ports:
      - "8088:8086"
    volumes:
      - db3-data:/var/lib/chinflux
    environment:
      CHINFLUX__SERVER__BIND_ADDRESS: "0.0.0.0"
      CHINFLUX__SERVER__PORT: "8086"
      CHINFLUX__CLUSTER__ENABLED: "true"
      CHINFLUX__CLUSTER__NODE_ID: "3"
      CHINFLUX__CLUSTER__CLUSTER_ADDR: "db3:8086"
      CHINFLUX__CLUSTER__PEERS: "db1:8086,db2:8086"
      CHINFLUX__CLUSTER__REPLICATION_LOG_DIR: "/var/lib/chinflux/replication_log"
    networks:
      - cluster

volumes:
  db1-data:
  db2-data:
  db3-data:

networks:
  cluster:
    driver: bridge

Start:

docker compose up -d

Point clients at any published port (8086, 8087, or 8088 above); each maps to the same HTTP server, so Prometheus can scrape http://localhost:8086/metrics, http://localhost:8087/metrics, and http://localhost:8088/metrics. Every node should be able to reach every other node on cluster_addr (here, db1:8086, db2:8086, db3:8086 over the cluster network).

For VMs or bare metal instead of Compose, use real IPs or DNS names in cluster_addr and peers the same way. See configuration.md and operations.md for the full cluster option list.