Development

This section is for contributing to Orchard’s source code: running it from a clone, making changes, and testing them. It is separate from the Install guide, which is for operators running a released build against their own services.

What Orchard is built from

Orchard is a monorepo with the client and server in their own directories:

Part	Location	Stack
Client	src/client	Angular, Angular Material
Server	src/server	NestJS, GraphQL (Apollo)
Shared	src/shared	GraphQL types generated from the server schema

The server stores its data with TypeORM in an SQLite database.

Prerequisites

• Node.js v22 (the version pinned in .nvmrc), which includes npm.
• git, to clone the repository.
• Docker with the Compose plugin, for the end-to-end tests.
• Bitcoin full node for the Oracle and end-to-end tests.
• Bitcoin, Lightning, and Cashu Mint on regtest for local development. Polar is useful for setting up a regtest environment.
• Ollama for the AI development and end-to-end tests.

Contributing changes

1. Fork cashubtc/orchard on GitHub, then clone your fork:

   git clone https://github.com/<you>/orchard.git
   cd orchard

2. Add the canonical repository as upstream so you can keep your fork in sync:

   git remote add upstream https://github.com/cashubtc/orchard.git

3. Create a branch for your change:

   git checkout -b my-change

4. Make your changes and run the tests and checks before pushing.

5. Push to your fork and open a pull request against cashubtc/orchard:

   git push -u origin my-change

Updating your fork

Before starting new work, pull in the latest changes so your branch stays current:

git fetch upstream
git rebase upstream/master

New to the codebase? Running Locally walks through getting Orchard running from source.

In this section

Running Locally Run the client and server dev processes, plus the configuration specific to development.

Testing & CI Run the server and client unit tests, formatting, and linting: the same checks CI runs.

End-to-End Testing Run Playwright against full Docker stacks: Bitcoin, Lightning, a mint, and Orchard from source.