Connect Orchard

Orchard, your sovereign bank in cyberspace: the web app that wraps the stack you just built. It connects to your Bitcoin node, your Lightning node, and your Cashu mint, and surfaces them in one dashboard for a simplified operational interface. This is the last step.

Like every other service, Orchard runs under its own user and points at endpoints you already configured.

What this step covers

• An isolated orchard user that runs the app and reads only what it needs.
• Orchard built from source and run as a service.
• Connections to the stack you built: your mint (its API, database, and management gRPC), plus your Lightning and Bitcoin nodes.
• Private access to the dashboard over your local network with HTTPS, or a Tor hidden service for remote access.

Requirements

• The full stack from this walkthrough running: system, Bitcoin, Lightning, and the Cashu mint, with the mint’s management gRPC enabled (it is, in the mint step’s config.toml).
• Node.js 22, which Orchard requires.
• The Orchard setup key you wrote down in the System step.

Preparations

Check Node + NPM

• With user admin, check that Node.js 22 is installed

node -v

Example of expected output:

v22.14.0

If the version is below 22 or Node is missing, install it with MiniBolt’s Node + NPM guide, then come back here.

Create the Orchard database role

Orchard reads the mint’s database and can perform backups, but it never writes to it: changes go through the management gRPC. Give it a dedicated role with read-only access to the cdk_mintd database, scoped so it cannot read your Lightning node’s database on the same instance.

• With user admin, create the role and grant it read access. The mint created its tables on first start in the previous step, so the grants apply to them

sudo -u postgres psql <<'SQL'
CREATE ROLE orchard WITH LOGIN PASSWORD 'your-orchard-db-password';
GRANT CONNECT ON DATABASE cdk_mintd TO orchard;
\c cdk_mintd
GRANT USAGE ON SCHEMA public TO orchard;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO orchard;
GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO orchard;
ALTER DEFAULT PRIVILEGES FOR ROLE cdk_mintd IN SCHEMA public GRANT SELECT ON TABLES TO orchard;
ALTER DEFAULT PRIVILEGES FOR ROLE cdk_mintd IN SCHEMA public GRANT SELECT ON SEQUENCES TO orchard;
SQL

A read-only role is all pg_dump needs, so the same grant both feeds the dashboard and lets Orchard back the mint up.

Restore needs more than read-only

This read-only role cannot restore a backup from Orchard: a restore drops and recreates the mint’s tables, which a SELECT-only role is not allowed to do, so the Restore button will fail. That is the safer default so Orchard can never write to or wipe your mint database. On the rare occasion you need to restore, load the backup file you downloaded from Orchard from the command line as the database owner instead:

sudo -u postgres psql cdk_mintd < backup.sql

Installation

Create the orchard user & group

Give Orchard its own unprivileged user, the same as every other service in the stack.

• With user admin, create the orchard user and group

sudo adduser --disabled-password --gecos "" orchard

• Add it to the lnd group so it can read your Lightning node’s certificate and macaroon for health checks

sudo usermod -aG lnd orchard

Create the data directory

Keep Orchard’s data under /data, the same place the rest of the stack stores its data.

• With user admin, create the directory and give it to the orchard user

sudo mkdir -p /data/orchard
sudo chown -R orchard:orchard /data/orchard

Download and build Orchard

Build as the orchard user so the app lives in its home.

• Change to the orchard user

sudo su - orchard

• Clone Orchard and check out the latest release. Do not run from master: it is unsupported and can leave the database in a state that will not upgrade cleanly

git clone https://github.com/cashubtc/orchard.git && cd orchard
git fetch --tags
git checkout v1.9.0

• Install the dependencies and build the app

npm install
npm run build

The build takes a few minutes on first run. Stay as the orchard user for the next step.

Configuration

Orchard is configured through a .env file. Only Orchard’s own settings are required; each service connection is optional and switched on by filling in its section.

• As the orchard user, copy the template and open it

cp .env.example .env
nano .env

• Fill in the following. The connection values are the ones you set in earlier steps

/home/orchard/orchard/.env

# --------------------------------------------
# Orchard Configs (required)
# --------------------------------------------
SETUP_KEY=your-saved-orchard-setup-key
SERVER_HOST=localhost
SERVER_PORT=3321
LOG_LEVEL=warn

# --------------------------------------------
# Orchard Configs (optional)
# --------------------------------------------
DATABASE_DIR=/data/orchard
TOR_PROXY_SERVER=socks://127.0.0.1:9050

# --------------------------------------------
# Bitcoin Configs (optional)
# --------------------------------------------
# valid types: core
BITCOIN_TYPE=core
BITCOIN_RPC_HOST=localhost
BITCOIN_RPC_PORT=8332
BITCOIN_RPC_USER=minibolt
BITCOIN_RPC_PASSWORD=your-bitcoin-rpc-password

# --------------------------------------------
# Lightning Configs (optional)
# --------------------------------------------
# valid types: lnd | cln
LIGHTNING_TYPE=lnd
LIGHTNING_RPC_HOST=localhost
LIGHTNING_RPC_PORT=10009
LIGHTNING_MACAROON=/data/lnd/data/chain/bitcoin/mainnet/readonly.macaroon
LIGHTNING_CERT=/data/lnd/tls.cert

# --------------------------------------------
# Cashu Configs (optional)
# --------------------------------------------
# valid types: cdk | nutshell
MINT_TYPE=cdk
MINT_API=http://localhost:8085
MINT_DATABASE=postgres://orchard:[email protected]:5432/cdk_mintd
MINT_RPC_HOST=localhost
MINT_RPC_PORT=8086
MINT_RPC_MTLS=false

• Save and exit, then make the Lightning macaroon readable by the lnd group and come back to admin

exit

sudo chmod g+r /data/lnd/data/chain/bitcoin/mainnet/readonly.macaroon

These are your Bitcoin step credentials

MiniBolt’s Bitcoin Core sets an rpcauth line in bitcoin.conf with the username minibolt and a password you chose, which is exactly what Orchard needs here. If you set a different username, match it.

If you secured the mint's gRPC with TLS

Setting MINT_RPC_MTLS=false matches the insecure gRPC the mint step sets up for an on-machine Orchard. If you took the mutual TLS option instead, leave MINT_RPC_MTLS at its default and point MINT_RPC_KEY, MINT_RPC_CERT, and MINT_RPC_CA at the client.key, client.pem, and ca.pem you generated.

Tor proxy

TOR_PROXY_SERVER routes Orchard’s outbound traffic through the Tor service your system setup already runs on 127.0.0.1:9050. If you did not set up Tor, comment that line out.

Create systemd service

Run Orchard under its own user so it starts on boot and restarts on failure.

• With user admin, create the service file

sudo nano /etc/systemd/system/orchard.service

• Paste the following configuration. Save and exit

/etc/systemd/system/orchard.service

# Orchard: systemd unit for Orchard
# /etc/systemd/system/orchard.service

[Unit]
Description=Orchard
Requires=cdk-mintd.service
After=cdk-mintd.service lnd.service bitcoind.service

[Service]
WorkingDirectory=/home/orchard/orchard
ExecStart=/usr/bin/npm run start

User=orchard
Group=orchard

# Hardening Measures
####################
PrivateTmp=true
ProtectSystem=full
NoNewPrivileges=true
PrivateDevices=true

[Install]
WantedBy=multi-user.target

• Reload systemd, then enable autoboot (optional)

sudo systemctl daemon-reload
sudo systemctl enable orchard

• Prepare orchard monitoring by the systemd journal. You can exit at any time with Ctrl-C

journalctl -fu orchard

Run

• With user admin, start the service

sudo systemctl start orchard

Validation

• Ensure Orchard is listening on its 3321 port, reachable only from this machine

sudo ss -tulpn | grep 3321

Example of expected output:

tcp   LISTEN 0   511   127.0.0.1:3321   0.0.0.0:*   users:(("node",pid=4242,fd=20))

Reverse proxy & Firewall

You set up Nginx as a reverse proxy with a self-signed certificate in MiniBolt’s security section. Add Orchard’s configuration to reach the dashboard over HTTPS on your local network.

• With user admin, create the reverse proxy configuration

sudo nano /etc/nginx/sites-available/orchard-reverse-proxy.conf

• Paste the following. Save and exit

server {
  listen 4321 ssl;
  error_page 497 =301 https://$host:$server_port$request_uri;

  location / {
    proxy_pass http://127.0.0.1:3321;
  }
}

• Enable the site, test the configuration, and reload Nginx

sudo ln -s /etc/nginx/sites-available/orchard-reverse-proxy.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

• Allow incoming HTTPS to the dashboard

sudo ufw allow 4321/tcp comment 'allow Orchard SSL from anywhere'

• Browse to https://minibolt.local:4321 (or your node’s IP, e.g. https://192.168.x.xxx:4321) and complete the first-run setup with your Orchard setup key. Your browser will warn about the self-signed certificate; click Advanced and proceed.

Orchard is up

The dashboard at https://minibolt.local:4321 means Orchard built, started, and is ready for you to create the admin account.

Extras (optional)

Remote access over Tor

For access from outside your local network, add a Tor hidden service that points at Orchard.

• With user admin, edit the torrc file

sudo nano +63 /etc/tor/torrc --linenumbers

• Add the following in the location-hidden-services section. Save and exit

# Hidden Service Orchard
HiddenServiceDir /var/lib/tor/hidden_service_orchard/
HiddenServiceVersion 3
HiddenServicePort 80 127.0.0.1:3321

• Reload Tor and read your onion address

sudo systemctl reload tor
sudo cat /var/lib/tor/hidden_service_orchard/hostname

Open that .onion address in the Tor browser from any device. Keep it to yourself: this is your admin dashboard.

Upgrade

• With user admin, stop the service

sudo systemctl stop orchard

• Change to the orchard user, check out the new release, and rebuild (the tag below is the latest; substitute another release tag to pin a specific version)

sudo su - orchard
cd orchard
git fetch --tags
git checkout v1.9.0
npm install
npm run build
exit

• With user admin, start the service again

sudo systemctl start orchard

Uninstall

This removes Orchard

Warning: this section removes Orchard and its settings. Only run these commands if you intend to uninstall.

Uninstall service

• With user admin, stop and disable the service, then remove the unit

sudo systemctl stop orchard
sudo systemctl disable orchard
sudo rm /etc/systemd/system/orchard.service
sudo systemctl daemon-reload

Delete user & group

• Delete the orchard user. Do not worry about the userdel: orchard mail spool (/var/mail/orchard) not found message

sudo userdel -rf orchard

• Remove Orchard’s data directory

sudo rm -rf /data/orchard

• Drop Orchard’s read-only database role

sudo -u postgres psql -d cdk_mintd -c "DROP OWNED BY orchard;"
sudo -u postgres psql -c "DROP ROLE orchard;"

Uninstall Tor hidden service

• If you added one, comment out or delete the Orchard block in torrc and reload Tor

sudo nano +63 /etc/tor/torrc --linenumbers
sudo systemctl reload tor

Remove the reverse proxy & firewall rule

• Remove Orchard’s Nginx site and its firewall rule, then reload Nginx

sudo rm /etc/nginx/sites-enabled/orchard-reverse-proxy.conf /etc/nginx/sites-available/orchard-reverse-proxy.conf
sudo systemctl reload nginx
sudo ufw delete allow 4321/tcp

Port reference

Port	Protocol	Use
3321	TCP (localhost)	Orchard dashboard, behind the Nginx and Tor proxies
4321	TCP (LAN)	Nginx HTTPS reverse proxy for the dashboard

Orchard has no internet-facing port. It is your admin dashboard, so it stays off the Cloudflare Tunnel and reachable only over your local network or Tor.

After new mint

Your stack is complete and managed: Bitcoin, Lightning, a mint, and Orchard tending all of it. From here, you operate from the dashboard.

Your Orchard Home, your crew, settings, and the services Orchard manages — at a glance.

Backup & Restore Keep a current copy of the mint database, and restore it when you need to.