Run a node

Run with Docker

Start the node yourself, with the Docker command line or with Compose.

On this page

Host or bridge
Bridge mode
Ping checks in host mode

Use these commands when you manage your containers directly. Both build hopbits/agent:local from https://hopbits.io/releases/Dockerfile, which verifies the Linux release binary against SHA256SUMS and packages it on a non-root distroless base image without needing any registry login.

Docker CLI

sudo docker build -t hopbits/agent:local https://hopbits.io/releases/Dockerfile
sudo docker volume create hopbits-data

sudo docker run -d \
  --name hopbits-agent \
  --restart=always \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --network host \
  -e HOPBITS_NETWORK_MODE=host \
  -v hopbits-data:/var/lib/hopbits \
  hopbits/agent:local

sudo docker logs -f hopbits-agent

compose.yaml

services:
  hopbits-agent:
    build: https://hopbits.io/releases/Dockerfile
    image: hopbits/agent:local
    container_name: hopbits-agent
    restart: always
    network_mode: host
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    environment:
      - HOPBITS_NETWORK_MODE=host
    volumes:
      - hopbits-data:/var/lib/hopbits

volumes:
  hopbits-data:

Save it as compose.yaml, then start it and follow the log:

Linux shell

sudo docker compose up -d
sudo docker compose logs -f

Then read the pairing code from the log and pair the node.

Host or bridge

The node can use the host's network or Docker's bridge network. Host is the default.

	Host	Bridge
Docker flag	`--network host`	`--network bridge`
Setting	`HOPBITS_NETWORK_MODE=host`	`HOPBITS_NETWORK_MODE=bridge`
Ping checks	Need one setting on the host	Need one setting on the container
IPv6 targets	Allowed	Only when the gateway sees a public IPv6 address for the node

Bridge mode

The --sysctl line lets the container send pings without extra privileges.

Docker CLI

sudo docker build -t hopbits/agent:local https://hopbits.io/releases/Dockerfile
sudo docker volume create hopbits-data

sudo docker run -d \
  --name hopbits-agent \
  --restart=always \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --network bridge \
  --sysctl net.ipv4.ping_group_range="0 2147483647" \
  -e HOPBITS_NETWORK_MODE=bridge \
  -v hopbits-data:/var/lib/hopbits \
  hopbits/agent:local

Ping checks in host mode

With its capabilities dropped, a container on the host's network can only ping if the host allows unprivileged ping sockets:

Linux shell

sudo sysctl -w net.ipv4.ping_group_range="0 2147483647"

Without it the node still runs HTTP and TCP checks. It simply does not offer ping. To keep the setting after a reboot, put the same line in a file under /etc/sysctl.d/.