Installing Orchard

There are three ways to install Orchard. Choose whichever suits your setup:

1. Standard — built from source.
2. Docker — a container built from source.
3. Docker — a container from the published image.

Prerequisites

• A host machine — One you control, that is able to reach the services you manage (Bitcoin, Lightning, Cashu Mint).
• For the standard install — Node.js v22, which includes npm.
• For the Docker install — Docker with the Compose plugin.

Choosing a host machine

Orchard can run on a home server or a cloud-hosted machine. The more reliable the network and power the better. At least 4 GB of RAM is required when building from source.

Get the code

All install paths start from a checked-out release tag. Clone the repository and check out the latest release.

git clone https://github.com/cashubtc/orchard.git
cd orchard
git fetch --tags
git checkout v1.9.0   # latest release tag

Always run a release tag

Running from master is unsupported and may leave your database in a state that can’t be cleanly upgraded. Check out the latest tag from the releases page before installing or updating.

Configure

Before starting Orchard, create your .env from the example and fill it in:

cp .env.example .env
nano .env

At minimum set SETUP_KEY; everything else has a sensible default or is optional. The Configuration page walks through every option, including how to point Orchard at your Bitcoin, Lightning, and Cashu Mint services.

Install

Standard (Node.js)

Install dependencies, build the app, and start it:

npm install
npm run build
npm run start

Orchard now serves on SERVER_HOST:SERVER_PORT (localhost:3321 by default). Open that address to reach the dashboard.

Docker (from source)

Build the image from the checked-out source and start it in the background:

docker compose build
docker compose up -d

Docker (registry image)

Skip the build and pull the prebuilt image from GitHub Container Registry:

docker compose -f docker-compose.yml -f compose.image.yml up -d

The image defaults to latest. Pin a release by setting VERSION in .env, or prefix it onto the command:

VERSION=1.9.0 docker compose -f docker-compose.yml -f compose.image.yml up -d

Updating

To update, start by checking out the new release tag. Pick the tab that matches your setup.

Standard (Node.js)

Check out the new release tag, then rebuild and restart:

git fetch --tags
git checkout v1.9.0   # the latest release tag
npm install
npm run build
npm run start

Docker (from source)

Check out the new release tag, then rebuild the image and re-up:

git fetch --tags
git checkout v1.9.0   # the latest release tag
docker compose build
docker compose up -d

Docker (registry image)

Check out the new release tag too — the prebuilt image ships in the registry, but docker-compose.yml and .env.example still come from the checkout and can change between releases. Then re-up to pull the matching image:

git fetch --tags
git checkout v1.9.0   # the latest release tag
VERSION=1.9.0 docker compose -f docker-compose.yml -f compose.image.yml up -d

Or set VERSION in .env to match the tag and run the plain docker compose … up -d.

Check the release notes

Before updating, read the release notes for the version you’re moving to. They call out any migration steps or config changes you need to apply.