The Watchtower

Seed nodes, configuration, systemd and monitoring

Architecture of a seed node

In the Radicle network, not all participants are equal in terms of availability. When you turn off your laptop, your projects are no longer accessible to others. That is where seed nodes come in.

The role of a seed in the P2P network

A seed node is a computer that stays permanently connected to the Radicle network. Its role:

• Availability: it keeps a copy of the projects it follows, even when the authors are offline
• Discovery: it helps new peers find projects and other peers
• Relay: it transmits updates between peers that are not directly connected

# Without seed node:
Alice (online) <--> Bob (online)     OK!
Alice (offline) <--> Bob (online)   Bob can't access Alice's project

# With seed node:
Alice (offline)
    |
    v (Alice published before going offline)
  Seed Node (always online) <--> Bob (online)   Bob accesses the project!

Peer vs Seed - what's the difference?

Prerequisites for a seed node

To set up a seed node, you need a machine that is permanently connected. Here are the options:

The server

• VPS (Virtual Private Server): the most common solution. Providers like Hetzner, OVH, Scaleway or DigitalOcean offer VPS starting at 3-5 euros per month
• Raspberry Pi: a small computer at home, connected to your router. Economical but requires a static IP or dynamic DNS
• Dedicated server: for ambitious projects with lots of traffic

Minimum configuration

• OS: Linux (Debian, Ubuntu, Fedora) - recommended
• RAM: 512 MB minimum, 1 GB recommended
• Disk: 10 GB minimum (depends on number of tracked projects)
• Network: public IP, port 8776 accessible

Install radicle-node

The Radicle node is included in the rad installation you did in the previous quest. The component that runs the node is called radicle-node.

# If rad is already installed, the node is available
rad node --help

# Otherwise, install Radicle (see Quest 21)
curl -sSf https://radicle.xyz/install | sh

Verify components

# Verify all components are present
rad --version
rad node --version

# The binaries are located in:
ls ~/.radicle/bin/
# radicle-node  rad  ...

Node configuration

Your Radicle node's configuration file is located in ~/.radicle/config.json. This is where you define the behavior of your watchtower.

The configuration file

# Display current configuration
rad config

# The file is located here:
cat ~/.radicle/config.json

Here are the important parameters:

{
  "node": {
    "alias": "my-watchtower",
    "listen": ["0.0.0.0:8776"],
    "peers": {
      "type": "dynamic"
    },
    "connect": [],
    "externalAddresses": ["my-server.example.com:8776"],
    "policy": "allow",
    "scope": "all"
  }
}

Parameter details

Policies: track and block

Policies control which projects your node agrees to replicate:

# Track a specific project (replicate it on your node)
rad track rad:z2e7RaGkMUjH3dMhiKd5dm2E3pCXA

# Stop tracking a project
rad untrack rad:z2e7RaGkMUjH3dMhiKd5dm2E3pCXA

Open the firewall

For other peers to connect to your node, port 8776 (TCP) must be accessible from outside.

With UFW (Ubuntu / Debian)

# Open port 8776
sudo ufw allow 8776/tcp

# Check the rules
sudo ufw status

With firewalld (Fedora / RHEL)

# Open port 8776
sudo firewall-cmd --add-port=8776/tcp --permanent
sudo firewall-cmd --reload

# Verify
sudo firewall-cmd --list-ports

With iptables (advanced)

# Open port 8776
sudo iptables -A INPUT -p tcp --dport 8776 -j ACCEPT

Start and monitor the node

Start the node

# Start the Radicle node
rad node start

# The node starts and connects to the network
# You will see connection messages to peers

Check the status

# Node status
rad node status

# Displays:
# Node is running
# Listening on 0.0.0.0:8776
# Connected peers: 3
# Tracked repos: 5

Stop the node

# Stop gracefully
rad node stop

Track projects

A seed node is only useful if it replicates projects. Here's how to manage tracked projects:

# Track a project by its identifier
rad track rad:z2e7RaGkMUjH3dMhiKd5dm2E3pCXA

# List tracked / known projects
rad inspect

# Stop tracking a project
rad untrack rad:z2e7RaGkMUjH3dMhiKd5dm2E3pCXA

When you track a project, your node:

1. Downloads all project data (code, patches, issues)
2. Automatically synchronizes when updates arrive
3. Serves this data to other peers who request it

Monitoring and diagnostics

Node logs

# View logs in real time
rad node logs

# Filter logs by level
rad node logs --level info
rad node logs --level debug

Common diagnostics

# Check connectivity
rad node status

# View connected peers
rad node peers

# Test connection to a specific peer
rad node connect <node-id>@<address>:8776

Common problems

systemd service - a persistent seed

For a seed node to run permanently (even after a server reboot), you need to configure it as a systemd service.

Create the service file

# Create the systemd service file
sudo nano /etc/systemd/system/radicle-node.service

File contents:

[Unit]
Description=Radicle Node
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=radicle
ExecStart=/home/radicle/.radicle/bin/radicle-node
Restart=on-failure
RestartSec=5
Environment=RADICLE_HOME=/home/radicle/.radicle

[Install]
WantedBy=multi-user.target

Enable and start the service

# Reload systemd configuration
sudo systemctl daemon-reload

# Enable the service at boot
sudo systemctl enable radicle-node

# Start the service
sudo systemctl start radicle-node

# Check the status
sudo systemctl status radicle-node

Manage the service

# View service logs
sudo journalctl -u radicle-node -f

# Restart the service
sudo systemctl restart radicle-node

# Stop the service
sudo systemctl stop radicle-node

# Create a dedicated user
sudo useradd -m -s /bin/bash radicle

# Log in as radicle to initialize
sudo -u radicle bash
curl -sSf https://radicle.xyz/install | sh
rad auth
exit

Hands-on exercise - Launch a local node

# Verify rad is installed and you have an identity
rad --version
rad self

# If you don't have an identity, create one
rad auth

# Display your current configuration
rad config

# Note the parameters: listen, policy, scope

# Launch the node
rad node start

# Verify it's running
rad node status

# If you created a project in Quest 21, note its RID
# Otherwise, create one quickly:
mkdir test-seed && cd test-seed
git init -b main
echo "test" > file.txt
git add file.txt
git commit -m "test"
rad init

# Note the displayed RID

# In another terminal, track this project
rad track rad:<your-project-rid>

# Watch what the node is doing
rad node logs

# You should see connection and replication messages

# Stop the node
rad node stop

# Verify it's stopped
rad node status

Command summary