5.7 KiB

Raw Permalink Blame History

ChronoGrid Daemon — Headless Node Setup Guide

This guide covers building, configuring, and deploying the chronogrid-daemon binary as a persistent background peer node on Linux (systemd) and Windows.

1. Prerequisites

Requirement	Minimum Version	Notes
Rust toolchain	1.75	Install via rustup
OpenSSL dev libs	3.x	Linux only: `libssl-dev` (Debian/Ubuntu)
Strawberry Perl	5.x	Windows only: required by `openssl-sys` build script
OS keychain	—	Windows Credential Manager or Linux SecretService (libsecret)

2. Building the Binary

2.1 Windows (MSVC target)

cargo build --release --package chronogrid_daemon
# Output: target\release\chronogrid-daemon.exe

2.2 Linux (native)

cargo build --release --package chronogrid_daemon
# Output: target/release/chronogrid-daemon

2.3 Cross-compile for headless Linux server (from Windows)

rustup target add x86_64-unknown-linux-gnu
cargo build --release --package chronogrid_daemon --target x86_64-unknown-linux-gnu
# Output: target/x86_64-unknown-linux-gnu/release/chronogrid-daemon

3. Installation (Linux)

# Create a dedicated system user
sudo useradd --system --no-create-home --shell /usr/sbin/nologin chronogrid

# Install the binary
sudo install -m 755 target/release/chronogrid-daemon /usr/local/bin/chronogrid-daemon

# Create data and config directories
sudo mkdir -p /var/lib/chronogrid /etc/chronogrid
sudo chown -R chronogrid:chronogrid /var/lib/chronogrid
sudo chmod 750 /var/lib/chronogrid

# Install config
sudo cp apps/chronogrid_daemon/config.example.toml /etc/chronogrid/config.toml
sudo chown root:chronogrid /etc/chronogrid/config.toml
sudo chmod 640 /etc/chronogrid/config.toml

Cluster Swarm Key Distribution

All nodes in the same ChronoGrid cluster must share the same swarm key. The key is auto-generated on first boot at swarm_key_path. Copy it to all other nodes:

# Retrieve key from the first node
cat /var/lib/chronogrid/swarm.key

# Place it on additional nodes
sudo -u chronogrid cp swarm.key /var/lib/chronogrid/swarm.key
sudo chmod 600 /var/lib/chronogrid/swarm.key

4. systemd Service

Create /etc/systemd/system/chronogrid-daemon.service:

[Unit]
Description=ChronoGrid P2P Headless Peer Node
Documentation=https://git.kellsupport.com/chronogrid
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=chronogrid
Group=chronogrid
WorkingDirectory=/var/lib/chronogrid
ExecStart=/usr/local/bin/chronogrid-daemon \
    --config /etc/chronogrid/config.toml \
    --log-level info
Restart=on-failure
RestartSec=5
StartLimitIntervalSec=60
StartLimitBurst=5
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ReadWritePaths=/var/lib/chronogrid
ProtectHome=yes
CapabilityBoundingSet=
StandardOutput=journal
StandardError=journal
SyslogIdentifier=chronogrid-daemon

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable chronogrid-daemon
sudo systemctl start chronogrid-daemon
sudo journalctl -u chronogrid-daemon -f

5. CLI Reference

chronogrid-daemon [OPTIONS]

Options:
  -c, --config <PATH>      Path to TOML config file
      --db <PATH>          SQLCipher database path (overrides config)
      --log-level <LEVEL>  error | warn | info | debug | trace  [default: info]
  -h, --help               Print help
  -V, --version            Print version

RUST_LOG environment variable overrides --log-level and supports target-specific directives, e.g. RUST_LOG=chronogrid=debug,libp2p=warn.

6. Key Management & First Boot

On first boot the daemon:

Generates a new Ed25519 node keypair → saved to identity_path.
Generates a new 256-bit swarm key → saved to swarm_key_path.
Derives a 256-bit Argon2id database master key (node + swarm fingerprints + random salt).
Stores derived key + salt in the OS keychain:
- Linux: SecretService D-Bus (libsecret).
- Windows: Windows Credential Manager (DPAPI-backed).
Opens or creates the SQLCipher 4.x database at database.path.

On subsequent boots the key is retrieved from the keychain — no human passphrase needed.

Security Note: Protect swarm.key with mode 600. Any node that holds the swarm key can join the cluster.

7. Networking & Firewall

Default ports used by the daemon:

Protocol	Port	Purpose
TCP	7700	libp2p TCP transport (Noise XK)
UDP	7700	libp2p QUIC-v1 transport

# UFW (Ubuntu/Debian)
sudo ufw allow 7700/tcp comment "ChronoGrid P2P TCP"
sudo ufw allow 7700/udp comment "ChronoGrid P2P QUIC"

LAN discovery uses mDNS (multicast UDP 5353) — no extra firewall rules needed on local networks.

8. Upgrading

cargo build --release --package chronogrid_daemon
sudo systemctl stop chronogrid-daemon
sudo install -m 755 target/release/chronogrid-daemon /usr/local/bin/chronogrid-daemon
sudo systemctl start chronogrid-daemon

Schema DDL uses CREATE TABLE IF NOT EXISTS — migrations apply automatically without data loss.

9. Troubleshooting

Symptom	Likely Cause	Resolution
`Keychain retrieval failed`	`libsecret` not installed	Install `libsecret-1-dev`; ensure D-Bus session exists
`Failed to open encrypted database`	Corrupt DB or wrong key	Check keychain entry; restore from backup
`No valid listen addresses`	Invalid Multiaddr syntax	Verify `listen_addrs` in config
No peers discovered	Swarm key mismatch or firewall	Confirm all nodes share the same `swarm.key`; check firewall
High CPU on startup	Argon2id KDF (expected)	~1–2 s on first boot at 64 MiB / 3 iterations — normal

5.7 KiB Raw Permalink Blame History Unescape Escape