radicle

A Co-op Cloud recipe for a Radicle seed node with a self-hosted web explorer pointing at it.

It deploys three services from two images:

• node — radicle-node, the p2p seeding daemon (owns the identity key).
• httpd — radicle-httpd, the HTTP API the explorer reads from (internal).
• web — radicle-explorer (a Svelte SPA) served by nginx, which also reverse-proxies /api/v1/* to httpd. Because the browser hits the API at the same origin as the frontend, there is no CORS to configure and one TLS cert.

Traefik ──▶ web (nginx)  ─┬─ /            explorer SPA
                          └─ /api/v1/*  ─▶ httpd :8080 ─┐ shared RAD_HOME volume
                                                        └─ node (p2p :8776 on host)

• Category: Developer tools
• Status: 1, alpha
• Image: git.coopcloud.tech/c4dt/radicle, custom
• Healthcheck: Yes
• Backups: Yes (the radicle_home volume)
• Email: N/A
• Tests: N/A
• SSO: N/A

Deploy

abra app new radicle
abra app config <domain>     # set DOMAIN, RAD_ALIAS, RAD_EXTERNAL_ADDRESS
abra app deploy <domain>

Requirements

• A DNS A record for DOMAIN pointing at the swarm host.
• The p2p port (RAD_P2P_PORT, default 8776) open on the host firewall so peers can dial your node. Set RAD_EXTERNAL_ADDRESS=<domain>:8776.

What happens on first deploy

1. The node generates an Ed25519 identity key (encrypted with the keypass secret) and writes config.json into the radicle_home volume.
2. The seeding policy defaults to allow / all — a public seeder that seeds every repository announced to it. Change with RAD_SEEDING_POLICY / RAD_SEEDING_SCOPE (only applied on first deploy; edit config.json in the volume afterwards).
3. The explorer is configured (via /config.json) to use your node as its preferred seed.

Back up the radicle_home volume. It holds the node's identity key — losing it means losing the node's identity on the network.

Operating the node

Helpers in abra.sh wrap the rad CLI. Run them against the node service:

abra app cmd <domain> node node_id        # this seed's Node ID (share <nid>@<domain>:8776)
abra app cmd <domain> node node_status     # running state + connected peers
abra app cmd <domain> node inventory       # repositories being seeded
abra app cmd <domain> node routing         # who announces what
abra app cmd <domain> node seed_repo rad:z2...     # explicitly seed a repo
abra app cmd <domain> node unseed_repo rad:z2...
abra app cmd <domain> node connect_peer <nid>@<host>:<port>
abra app cmd <domain> node follow_peer <nid>

Images

Radicle publishes no official images, so this recipe builds two:

• git.coopcloud.tech/c4dt/radicle:<RADICLE_VERSION> — bundles rad, radicle-node and radicle-httpd (binaries verified from files.radicle.dev). See build/node/Dockerfile.
• git.coopcloud.tech/c4dt/radicle-explorer:<EXPLORER_VERSION> — the explorer SPA built with VITE_RUNTIME_CONFIG=true and served by nginx. See build/explorer/Dockerfile.

.drone.yml builds and pushes both on git tag (needs a privileged docker runner and a git_coopcloud_token secret with write:package). To build manually:

docker login git.coopcloud.tech
docker build --build-arg RADICLE_VERSION=1.9.1 --build-arg RADICLE_HTTPD_VERSION=0.26.0 \
  -t git.coopcloud.tech/c4dt/radicle:1.9.1 build/node
docker build --build-arg EXPLORER_REF=<commit> \
  -t git.coopcloud.tech/c4dt/radicle-explorer:<tag> build/explorer
docker push git.coopcloud.tech/c4dt/radicle:1.9.1
docker push git.coopcloud.tech/c4dt/radicle-explorer:<tag>

Version compatibility: the explorer's requiredApiVersion must satisfy the API version reported by radicle-httpd. Bump EXPLORER_VERSION and RADICLE_HTTPD_VERSION together and test before releasing.

License