Skip to content
SentinelSentinel Documentation

Gateway installation

Before starting, install Docker and the Compose plugin from the official Docker repository (Debian guide). The docker.io package bundled with Debian 12 does not include the docker compose v2 used here.

When installing Debian, leave the uplink port on DHCP and do not configure the rack LAN port; that port is set up by setup-host.sh.

  1. Edit host/gateway.env

    Variable Meaning
    RACK_IF the interface to the rack PoE switch (check with ip -br link; on Debian usually enp1s0, enp2s0, or enx<mac> for a USB adapter)
    RACK_IP, RACK_PREFIX the gateway IP on the rack LAN (default 10.10.0.1/24); the same as router, broker, NTP, and OTA server
    NTP_UPSTREAM Celestian’s NTP address (preferred); empty = only 0-3.id.pool.ntp.org. Nodes on the rack LAN cannot reach out, so this upstream is only for the gateway
    DHCP_START, DHCP_END, DHCP_LEASE the DHCP pool for Sentinel (default 10.10.0.10 – 10.10.0.250, 12 hours; large DCs: use a /23)

  2. Run the host setup

    Terminal window
    sudo ./host/setup-host.sh

    The script sets up the static rack LAN IP, DHCP (dnsmasq), NTP (chrony), and the firewall (nftables), and recognizes the Debian network manager by itself (ifupdown), NetworkManager, or systemd-networkd.

  3. Prepare .env

    Terminal window
    cp -n .env.example .env

    Make sure RACK_IP in .env equals host/gateway.env. Fill in the history and Celestian connection section (GATEWAY_ID, GATEWAY_KEY, WORKSPACE, CHANNEL, CELESTIAN_HOST, CELESTIAN_MODE). See Bridge to Celestian.

  4. Prepare mosquitto/conf.d/bridge.conf

    Copy bridge.conf.example to bridge.conf, then fill in <ID-gateway>, <device-key-gateway>, <workspace>, and <channel>.

  5. Run

    Terminal window
    docker compose up -d --build

    If a UPS is connected to NUT, add --profile ups.

Checking

Section titled “Checking”
Terminal window
docker compose ps
docker compose logs -f history        # queue summary every minute, the effective connection method
sudo nft list table inet celestian_gw # firewall drop counters
chronyc tracking                      # gateway clock and NTP upstream

A node plugged into the rack switch should get an IP from the pool, then appear online in Celestian within seconds.

Temporary gateway on a MacBook (testing)

Section titled “Temporary gateway on a MacBook (testing)”

While the mini PC is not yet available, a MacBook can serve as a gateway for testing: connect the PoE switch to the MacBook’s USB-Ethernet adapter, turn on Internet Sharing (share Wi-Fi to that adapter) so the MacBook becomes router and DHCP server, then run:

Terminal window
cd Gateway && docker compose -f docker-compose.yml -f docker-compose.mac.yml up -d

The local broker uses ports 11883 (MQTT 3.1.1, test tools) and 11884 (MQTT 5, Sentinel). Differences from a real gateway:

  • The MacBook does not serve NTP; nodes use the internet pool (needs an outbound route) or a manually filled ntp_server.
  • There is no rack LAN firewall; nodes can reach the internet through the MacBook.
  • If the switch is connected to an ordinary router, the gateway IP is not the MacBook; set mqtt_host on the node.
  • Test tools (celestianctl.py, sim_device.py) need --port 11883.
  • Clock check: GATEWAY_CLOCK_CHECK=off in .env.

With no hardware at all, nodes can be simulated with sim_device.py.