Tamanu Meta Server

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

The Meta service provides:

• a server discovery service for the Tamanu mobile app
• a server list and health check page
• a range of active versions
• download URLs to available artifacts for active versions

Get

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

ghcr.io/beyondessential/tamanu-meta:5.7.4

Develop

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

$ git clone [email protected]:beyondessential/tamanu-meta-server.git

• Install development dependencies:

$ just install-deps

This will install cargo-nextest, cargo-leptos, diesel CLI, cargo-release, git-cliff, 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 tamanu_meta):

$ export DATABASE_URL=postgres://localhost/tamanu_meta_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 tamanu_meta tamanu-meta-prod

Releasing

(You need write access to the main branch directly)

On the main branch:

$ just release minor

(or use patch or major instead of minor)

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.