# 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](https://rustup.rs) |
| 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)

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

### 2.2 Linux (native)

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

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

```powershell
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)

```bash
# 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:

```bash
# 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`:

```ini
[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
```

```bash
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:

1. Generates a new Ed25519 node keypair → saved to `identity_path`.
2. Generates a new 256-bit swarm key → saved to `swarm_key_path`.
3. Derives a 256-bit Argon2id database master key (node + swarm fingerprints + random salt).
4. Stores derived key + salt in the OS keychain:
   - **Linux**: SecretService D-Bus (libsecret).
   - **Windows**: Windows Credential Manager (DPAPI-backed).
5. 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 |

```bash
# 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

```bash
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 |