Docs

Deployment

Run a node, bootstrap, or provider

The XE network runs three deployable components managed by pm2 on each host, with Caddy as the reverse proxy and TLS terminator. Static web assets are served directly from disk.

#Components

ComponentStackDeploymentPurpose
Core nodeGo, libp2p, BadgerDBNative binary via pm2Block lattice, consensus, networking, HTTP API, VM management
ExplorerSvelteKit 2, Svelte 5Static files on diskBlock explorer and network dashboard
Web walletSvelteKit 2, Svelte 5Static files on diskBrowser-based wallet
DocsMkDocs MaterialStatic files on diskTechnical documentation

#Architecture

diagram
                    ┌─────────────┐                    │   Caddy     │ :80/:443                    │  (pm2)      │                    └──────┬──────┘                           │              ┌────────────┼────────────┬────────────┐              │            │            │            │              ▼            ▼            ▼            ▼        /api/*       /wallet/*     /docs/*         /*     ┌─────────┐   ┌──────────┐  ┌──────────┐  ┌──────────┐     │ xe-node │   │  Static  │  │  Static  │  │  Static  │     │  (pm2)  │   │  files   │  │  files   │  │  files   │     │ :8080   │   │ /opt/xe/ │  │ /opt/xe/ │  │ /opt/xe/ │     └─────────┘   │ web/     │  │ web/     │  │ web/     │                   │ wallet/  │  │ docs/    │  │ explorer/│                   └──────────┘  └──────────┘  └──────────┘

pm2 manages two processes:

  • xe-node — the core Go binary, running as the xe service user (non-root, required for Lima VM support)
  • caddy — reverse proxy and static file server, running as root for port 80/443 binding

Static web assets are built by CI and rsynced to /opt/xe/web/ on each host:

PathContent
/opt/xe/web/explorer/Explorer SPA build
/opt/xe/web/wallet/Wallet SPA build
/opt/xe/web/docs/MkDocs static build

#Caddy routing

Caddy handles TLS termination (automatic Let's Encrypt certificates) and routes requests:

PathTargetBehaviour
/api/*localhost:8080Reverse proxy to xe-node HTTP API (path prefix stripped)
/wallet/*/opt/xe/web/wallet/Static file serving with SPA fallback
/docs/*/opt/xe/web/docs/Static file serving
/*/opt/xe/web/explorer/Explorer SPA with fallback to index.html

Each node also has a CORE_DOMAIN (e.g., ldn.core.test.network) that proxies directly to the node API without path stripping — used for direct API access.

text
{$DOMAIN} {    redir /wallet /wallet/ 301    redir /docs /docs/ 301    handle_path /api/* {        reverse_proxy localhost:8080    }    handle_path /wallet/* {        root * /opt/xe/web/wallet        try_files {path} /index.html        file_server    }    handle_path /docs/* {        root * /opt/xe/web/docs        file_server    }    handle {        root * /opt/xe/web/explorer        try_files {path} /index.html        file_server    }}{$CORE_DOMAIN} {    reverse_proxy localhost:8080}

#Deployment targets

The test network runs across four nodes:

HostRegionDomainCore DomainRole
LondonUKldn.test.networkldn.core.test.networkFull stack
New YorkUSnyc.test.networknyc.core.test.networkFull stack
FrankfurtDEffm.test.networkffm.core.test.networkFull stack
bm1DE (bare metal)—bm1.core.test.networkProvider only

The first three hosts run the full stack (xe-node + Caddy + static sites). bm1 is a bare-metal server running only xe-node in provider mode — no Caddy, no static sites. It provides compute resources (4 vCPUs, 8 GB RAM, 50 GB disk) for VM leasing via Lima/QEMU with KVM acceleration.

Nodes bootstrap to each other using -dial flags with the other nodes' multiaddrs.

#CI/CD

Deployment is automated via GitHub Actions across four repositories:

diagram
Push to master    │    ▼Build (per repo)    ├── core:     go build → xe-node binary    ├── explorer: npm build → static files    ├── wallet:   npm build → static files    └── docs:     mkdocs build → static files    │    ▼Deploy (parallel to 3 hosts)    ├── core:     scp binary → pm2 restart xe-node    ├── explorer: rsync build/ → /opt/xe/web/explorer/    ├── wallet:   rsync build/ → /opt/xe/web/wallet/    └── docs:     rsync site/ → /opt/xe/web/docs/

The core CI also syncs Caddy config and ecosystem files to each host, then restarts Caddy if config changed.

#Process management

pm2 configuration lives at /opt/xe/deploy/ecosystem.config.js. It reads the .env file directly to get NODE_FLAGS:

go
const fs = require('fs');const env = loadEnv('/opt/xe/deploy/.env'); module.exports = {  apps: [    {      name: 'xe-node',      script: '/usr/local/bin/xe-node',      interpreter: 'none',      args: env.NODE_FLAGS || '',      uid: 'xe',      gid: 'xe',      env: { HOME: '/home/xe' },      restart_delay: 5000,      max_restarts: 10,    },    {      name: 'caddy',      script: '/usr/bin/caddy',      interpreter: 'none',      args: 'run --config /etc/caddy/Caddyfile --envfile /opt/xe/deploy/.env',      restart_delay: 5000,      max_restarts: 10,    }  ]};

#See also