Deployment

Production deployment guide for Routstr Provider nodes.

Quick Start (Recommended)

The recommended way to run a provider node is to clone the repository at the latest release and start the stack with Docker Compose. Compose builds both the node and the admin dashboard from source, so there is no image to pull and no dashboard build to keep in sync with the node.

git clone https://github.com/Routstr/routstr-core.git
cd routstr-core

# Check out a release (v0.4.7 is current — see the releases page for the newest tag)
git checkout v0.4.7

# Compose reads its configuration from .env
cp .env.example .env

docker compose up -d

Then open your node: - API & Admin Dashboard: http://localhost:8000 - Admin login: the password is generated and logged once on first start

docker compose logs routstr | grep -i admin

The first start takes a few minutes

docker compose up builds both images locally, and the Next.js dashboard build is the slow part. Later starts reuse the built images.

Always tracking the newest release

To check out whatever releases/latest currently points at, use:

git clone https://github.com/Routstr/routstr-core.git
cd routstr-core
git checkout "$(curl -sSL -o /dev/null -w '%{url_effective}' \
  https://github.com/Routstr/routstr-core/releases/latest | sed 's|.*/tag/||')"

Omitting the git checkout entirely leaves you on main — newer, but not a tested release.

---

What Docker Compose Starts

compose.yml brings up three services:

1. ui — builds the Next.js admin dashboard and copies the result into the shared ./ui_out volume.
2. routstr — the Python node, serving the API and the dashboard built above.
3. tor — serves the node as a .onion hidden service, so no port forwarding is needed. See Tor Support for how to read your .onion address.

---

Pre-Configuration (Optional)

Everything can be configured from the dashboard after first start, but you can pre-configure a deployment by editing the .env file you created above:

# Upstream (optional — can also be set from the dashboard)
UPSTREAM_BASE_URL=https://api.openai.com/v1
UPSTREAM_API_KEY=sk-proj-...

# Encrypts node secrets at rest. Optional — if unset, a key is generated next to
# your database (on the same volume) and its file is named once for backup. Set
# it explicitly to manage the key yourself.
ROUTSTR_SECRET_KEY=

# Node identity
NAME=My Provider Node
DESCRIPTION=Fast GPT-4 access via Lightning

# Lightning withdrawals
RECEIVE_LN_ADDRESS=me@walletofsatoshi.com

The admin password is generated and logged once on first start; set ADMIN_PASSWORD only as a legacy seed for an existing deployment.

Secret key persistence

If you leave ROUTSTR_SECRET_KEY unset, the node generates one and stores it as routstr_secret.key next to your database, so it persists alongside your data — just include that in your backups. For stronger isolation (keeping the key off the data volume), set ROUTSTR_SECRET_KEY from a secrets manager instead.

See Configuration for all available options.

---

Persistence

With the default compose.yml the repository directory is mounted into the container, so everything Routstr persists stays in the directory you cloned:

Path	Contents
keys.db	SQLite database (settings, API keys, sessions)
routstr_secret.key	Auto-generated master key, written beside the database when ROUTSTR_SECRET_KEY is unset
.wallet/	Cashu wallet data (your Bitcoin!)
logs/	Node logs

Back Up Your Data

Your cloned directory holds your wallet and your master key. Losing it means losing funds. Back it up regularly — and don't delete the checkout to "start fresh" without copying keys.db, routstr_secret.key and .wallet/ first.

---

Reverse Proxy (Optional)

For custom domains and SSL, use a reverse proxy like Caddy or nginx.

Caddy Example

api.yournode.com {
    reverse_proxy localhost:8000
}

nginx Example

server {
    listen 443 ssl;
    server_name api.yournode.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

---

Updates

Check out the new release and rebuild:

git fetch --tags
git checkout v0.4.7   # or the tag you are moving to
docker compose up -d --build

--build is required: Compose reuses an existing image for a service unless you ask it to rebuild.

Back up first

Copy keys.db, routstr_secret.key and .wallet/ before updating, and read the release notes for the version you are moving to.

---

Building Without Starting

docker compose up -d already builds from source. To build the images explicitly without starting them:

docker compose build

To build only the node image (the dashboard must already be built into ./ui_out):

docker build -t routstr-node .