Canopy

Tamanu is an open-source patient-level electronic health records system for mobile and desktop.

Canopy provides:

• a server discovery service for the Tamanu mobile app
• the full list of available versions of Tamanu
• download URLs to available artifacts for active versions

and, internally:

• a global view of server status and healthchecks
• backup management
• associated tooling (bestool)

This is not expected to be usefully run by any other organisation; as a public-interest non-profit, BES International publishes almost all of its software as open-source.

Get

We have a container image for linux/amd64 and linux/arm64:

ghcr.io/beyondessential/canopy:latest

Each push to main builds and publishes a new image (also tagged sha-<short> for the source commit) and triggers a pulumi deploy.

Develop

• Install Rustup, which will install Rust and Cargo.
• Install just command runner
• Clone the repo via git:

$ git clone git@github.com:beyondessential/canopy.git

• Install development dependencies:

$ just install-deps

This will install cargo-nextest, diesel CLI, and watchexec.

Quick Start

• Create a new blank postgres database.
• Optionally set the DATABASE_URL environment variable (if your database isn't named the default canopy):

$ export DATABASE_URL=postgres://localhost/canopy_dev

• Run migrations:

$ just migrate

• Build the project:

$ just check

• Run public server:

$ cargo watch-public

• Run private server:

$ just watch-private

• Run other binaries:

$ cargo run --bin binary_name_here

• Tests:

$ just test

• Lints:

$ just lint

• Format, lint, and test in one command:

$ just dev

Available Commands

See all available commands:

$ just --list

We recommend using Rust Analyzer or Rust Rover for development.

Migrations

1. Create a migration:

$ just migration some_name_here

2. Write the migration's up.sql and down.sql

3. Run the pending migrations:

$ just migrate

4. Test your down:

$ just migrate-redo

Download a database

You'll need to have kubectl installed and authorised.

# just download-db {database name} {kubernetes namespace} [dump file]
$ just download-db canopy canopy-prod

Public API Authentication

The public-server binary serves the public API and views, which are expected to be exposed to the internet (in production behind an ingress gateway or reverse proxy).

The mtls-certificate (or ssl-client-cert) header should contain a PEM-encoded (optionally URL-encoded) X509 certificate.

To get a certificate, run:

$ just identity

This will write the identity.crt.pem and identity.key.pem.

You can then put it in an environment variable:

$ export MTLS_CERT="$(jq -sRr @uri identity.crt.pem)"

and then use curl like:

$ curl -H "mtls-certificate: $MTLS_CERT" ...

In production

In production, the header should be set from a client certificate, as terminated by a reverse proxy or load balancer, and any matching header on the incoming requests should be stripped.

• Nginx: use the $ssl_client_escaped_cert variable.
• Caddy: use the {http.request.tls.client.certificate_pem} placeholder.

MCP

Claude Code:

$ claude mcp add --transport http canopy https://canopy.tail53aef.ts.net/api/mcp

Then ask it things like "list the servers in group X" or "which backups are overdue".