Configuration

Configure Orchard by setting environment variables in a .env file in the project root. Copy the template and edit it:

cp .env.example .env
nano .env

Orchard

First, configure the core of the application. Some configs are required, others are optional.

Required

SETUP_KEY is the one you must set; the rest are shown with their defaults. Copy the block into .env and make applicable changes.

SETUP_KEY=<YOUR_SETUP_KEY>  # required — guards first-run setup and admin access
SERVER_HOST=localhost       # address the server binds to
SERVER_PORT=3321            # port Orchard listens on
LOG_LEVEL=warn              # log verbosity

Variable	Description	Default
SETUP_KEY	Secret that guards first-run setup and admin access. Set this.	—
SERVER_HOST	Address the server binds to.	localhost
SERVER_PORT	Port Orchard listens on.	3321
LOG_LEVEL	Log verbosity, quietest to loudest: fatal, error, warn, info, debug, verbose.	warn

Debugging a problem?

Set LOG_LEVEL=debug to surface the detailed logs that help pin down what’s going wrong.

Defaults

Orchard uses these settings, falling back to the defaults shown when they’re unset.

BASE_PATH=api         # URL path prefix for the API
THROTTLE_TTL=60000    # rate-limit window, in milliseconds
THROTTLE_LIMIT=20     # requests allowed per window
DATABASE_DIR=data     # directory for Orchard's database

Variable	Description	Default
BASE_PATH	URL path prefix for the API.	api
THROTTLE_TTL	Rate-limit window, in milliseconds.	60000
THROTTLE_LIMIT	Requests allowed per window.	20
DATABASE_DIR	Directory for Orchard’s own database (<dir>/orchard.db).	data

Optional

These settings are optional. Set them to route traffic through a proxy, compress responses, or pin the key that encrypts stored settings. Leave any of them blank to keep the default behavior.

TOR_PROXY_SERVER=           # SOCKS proxy for outbound traffic
SERVER_COMPRESSION=false    # compress HTTP responses
CRYPTO_KEY=                 # encryption key for app settings

Variable	Description	Default
TOR_PROXY_SERVER	SOCKS proxy for outbound connections, e.g. socks://127.0.0.1:9050.	unset
SERVER_COMPRESSION	Enable HTTP response compression. Set to true only if nothing upstream (a reverse proxy or CDN) already compresses responses.	false
CRYPTO_KEY	Key that encrypts stored settings. Auto-generated and saved if unset; set it to control the value yourself.	auto

Services

Each service below is optional and independent of the rest. Connect whichever fits your setup. Each unlocks its matching features in the application. That might be a full stack, just your mint, or only your Lightning node.

To omit a service, leave the section blank or comment it out.

Bitcoin

Point Orchard at your Bitcoin node over RPC. The host and port below are the standard Bitcoin Core values; set the credentials to match your bitcoin.conf.

BITCOIN_TYPE=core               # implementation
BITCOIN_RPC_HOST=localhost      # RPC host
BITCOIN_RPC_PORT=8332           # RPC port
BITCOIN_RPC_USER=<user>         # RPC username
BITCOIN_RPC_PASSWORD=<password> # RPC password

Variable	Description	Typical
BITCOIN_TYPE	Node implementation. Valid: core (Knots is compatible).	core
BITCOIN_RPC_HOST	RPC host.	localhost
BITCOIN_RPC_PORT	RPC port.	8332
BITCOIN_RPC_USER	RPC username.	—
BITCOIN_RPC_PASSWORD	RPC password.	—

Lightning

Connect the Lightning node that sits between Bitcoin and your mint. Pick your implementation below; the two authenticate differently (LND with a macaroon, CLN with mutual TLS), so each tab shows only the settings it needs.

LND

LND authenticates with a macaroon and trusts the node’s TLS certificate.

LIGHTNING_TYPE=lnd                   # implementation
LIGHTNING_RPC_HOST=localhost         # gRPC host
LIGHTNING_RPC_PORT=10009             # gRPC port (LND's default)
LIGHTNING_MACAROON=<admin.macaroon>  # path Orchard authenticates with
LIGHTNING_CERT=<tls.cert>            # path to the node's TLS cert

Variable	Description	Typical
LIGHTNING_TYPE	Set to lnd.	lnd
LIGHTNING_RPC_HOST	gRPC host.	localhost
LIGHTNING_RPC_PORT	gRPC port.	10009
LIGHTNING_MACAROON	Path to the macaroon Orchard authenticates with (e.g. admin.macaroon).	—
LIGHTNING_CERT	Path to the node’s TLS certificate (tls.cert).	—

CLN

CLN uses mutual TLS: a client certificate and key, plus the CA that signed them. No macaroon.

LIGHTNING_TYPE=cln              # implementation
LIGHTNING_RPC_HOST=localhost    # gRPC host
LIGHTNING_RPC_PORT=<grpc-port>  # gRPC port (matches CLN's grpc-port)
LIGHTNING_CERT=<client.pem>     # client certificate
LIGHTNING_KEY=<client-key.pem>  # client key
LIGHTNING_CA=<ca.pem>           # CA certificate

Variable	Description	Typical
LIGHTNING_TYPE	Set to cln.	cln
LIGHTNING_RPC_HOST	gRPC host.	localhost
LIGHTNING_RPC_PORT	gRPC port, matching the grpc-port in your CLN config.	—
LIGHTNING_CERT	Path to the client certificate (client.pem).	—
LIGHTNING_KEY	Path to the client key (client-key.pem).	—
LIGHTNING_CA	Path to the CA certificate (ca.pem).	—

Taproot Assets

Manage Lightning-native assets with your taproot assets daemon. The host and port below are tapd’s standard values; point the macaroon and certificate at your tapd instance.

TAPROOT_ASSETS_TYPE=tapd                  # implementation
TAPROOT_ASSETS_RPC_HOST=localhost         # gRPC host
TAPROOT_ASSETS_RPC_PORT=10029             # gRPC port (tapd's default)
TAPROOT_ASSETS_MACAROON=<admin.macaroon>  # path Orchard authenticates with
TAPROOT_ASSETS_CERT=<tls.cert>            # path to tapd's TLS cert

Variable	Description	Typical
TAPROOT_ASSETS_TYPE	Daemon implementation. Valid: tapd.	tapd
TAPROOT_ASSETS_RPC_HOST	gRPC host.	localhost
TAPROOT_ASSETS_RPC_PORT	gRPC port.	10029
TAPROOT_ASSETS_MACAROON	Path to the tapd macaroon Orchard authenticates with.	—
TAPROOT_ASSETS_CERT	Path to tapd’s TLS certificate.	—

Cashu Mint

Connect your Cashu Mint to Orchard. Orchard reaches the mint three ways:

• Public API — to read mint info and the features it supports.
• Database — to read rich data the RPC doesn’t surface (yet).
• Management RPC — for management actions.

Set the implementation in Connection; the Database and Management RPC are each configured a little differently, depending on the implementation.

Connection

cdk

MINT_TYPE=cdk
MINT_API=http://localhost:8085   # cdk-mintd's HTTP API

Nutshell

MINT_TYPE=nutshell
MINT_API=http://localhost:3338   # Nutshell's HTTP API

Database

Orchard reads the mint’s database directly. The type is inferred from the value: a file path is SQLite, a postgres:// URL is Postgres.

SQLite

MINT_DATABASE=/path/to/mint.sqlite3   # file Orchard reads directly

Postgres

MINT_DATABASE=postgres://user:pass@localhost:5432/mint
# append ?sslmode=require to encrypt without verifying the server

Postgres + TLS

Verified TLS needs the CA. Add the client cert and key only for mutual TLS.

MINT_DATABASE=postgres://user:pass@localhost:5432/mint?sslmode=verify-full
MINT_DATABASE_CA=<ca.pem>           # required for verify-ca / verify-full
MINT_DATABASE_CERT=<client.pem>     # mutual TLS only
MINT_DATABASE_KEY=<client-key.pem>  # mutual TLS only

Management RPC

Orchard manages the mint over its gRPC interface. cdk and Nutshell both serve it the same two ways, insecure or mutual TLS with client certificates, so match Orchard’s settings to how the mint serves the RPC.

Insecure

For a mint on the same machine, reachable only from it, serving the RPC without TLS. cdk-mintd does this by default, until a TLS certificate directory exists; Nutshell when mint_rpc_server_mutual_tls=false.

MINT_RPC_HOST=localhost
MINT_RPC_PORT=8086       # the mint's management gRPC port
MINT_RPC_MTLS=false      # connect without TLS

Mutual TLS

For a mint Orchard reaches over the network, serving over mutual TLS. cdk-mintd does this once its TLS certificate directory exists; Nutshell by its default mint_rpc_server_mutual_tls=true. On Orchard’s side, MINT_RPC_MTLS turns on automatically once the key, cert, and CA are all set.

MINT_RPC_HOST=<mint-host>
MINT_RPC_PORT=8086          # the mint's management gRPC port
MINT_RPC_KEY=<client.key>   # client key
MINT_RPC_CERT=<client.pem>  # client certificate
MINT_RPC_CA=<ca.pem>        # CA certificate

Variable	Description	Typical
MINT_TYPE	Mint implementation. Valid: cdk, nutshell.	—
MINT_API	The mint’s HTTP API.	8085 (cdk), 3338 (Nutshell)
MINT_DATABASE	Database Orchard reads directly: a SQLite file path, or a postgres:// URL. The type is inferred from the value.	—
MINT_DATABASE_CA	CA certificate, for Postgres with sslmode=verify-ca/verify-full.	—
MINT_DATABASE_CERT	Client certificate, for mutual TLS to Postgres.	—
MINT_DATABASE_KEY	Client key, for mutual TLS to Postgres.	—
MINT_RPC_HOST	Mint management gRPC host.	localhost
MINT_RPC_PORT	Mint management gRPC port.	8086
MINT_RPC_MTLS	Force the RPC’s mutual TLS on (true) or off (false). Auto-on when the key, cert, and CA are all set.	auto
MINT_RPC_KEY	Path to the RPC client key.	—
MINT_RPC_CERT	Path to the RPC client certificate.	—
MINT_RPC_CA	Path to the RPC CA certificate.	—