One lab, one database.

App or server?

BioManager is the same program in both cases; what differs is where the database lives and who can reach it.

Choose how

Three questions settle it:

1. Just you? Use the desktop app (A). Done.
2. Everyone in one building, on the same network? A lab computer on your network (B) works, or ask IT for a university server (C).
3. People at home, on phones on mobile data, or across sites? A cloud VM with Tailscale (D) — private, free, and reachable anywhere. This is what we recommend for most labs. Only if you want an ordinary web address that works with no app at all, use your own domain (E).

Prices are what these services charged in September 2026; check before you sign up. Every server option (B–E) includes nightly backups, a weekly restore test and HTTPS.

A · One computer: the desktop app

Free · 2 minutes · private to that computer

1. Download BioManager for your computer: macOS (Apple silicon or Intel), Windows or Linux.
2. Mac: unzip, drag BioManager to Applications, then the first time right-click → Open → Open. Windows: extract the zip, open BioManager.exe, and at the warning choose More info → Run anyway. Linux: mark the AppImage executable and open it.
3. Create your account and answer the set-up questions. See the user guide.

Your data lives outside the app (~/Library/Application Support/Biomanager/ on a Mac, %APPDATA%\Biomanager\ on Windows, ~/.local/share/Biomanager/ on Linux), so updating never touches it. Back that folder up with Time Machine or File History, and never keep it in Dropbox, OneDrive, Google Drive or iCloud Drive: syncing corrupts databases.

A few people on one network can share one computer's lab without a server: Settings → Devices → Share this lab on the network makes it the lab's master copy, opened by the others at the address it shows. The computer must stay on, nothing is backed up nightly as on a server, and the connection isn't encrypted: fine on a lab network you trust, a server for anything more (Devices).

B · A lab computer on your network

Free with a spare computer · 1 hour · reachable on your lab or campus network

Any computer that stays switched on can be the server: a Linux PC, an old desktop, or a Mac mini. The lab opens it at an address like https://192.168.1.50. It can't be reached from outside your network unless your campus VPN puts people inside it.

1. Give the computer a fixed address. Ask IT for a fixed IP address or a DNS name for it (for example biomanager.bio.youruni.edu), so the address never changes. Turn off sleep.
2. Install Docker. Linux: curl -fsSL https://get.docker.com | sudo sh, then sudo usermod -aG docker $USER and log in again. Mac: install Docker Desktop (free for education and small organisations) or OrbStack, and set it to start at login.
3. Get the server bundle into /opt/biomanager:

   sudo mkdir -p /opt/biomanager && sudo chown "$USER" /opt/biomanager
   curl -fsSL -o /tmp/biomanager-server.tar.gz \
     https://github.com/gaspolymerase/biomanager/releases/latest/download/biomanager-server.tar.gz
   tar -xzf /tmp/biomanager-server.tar.gz -C /opt/biomanager
   cd /opt/biomanager/Biomanager/deploy
   host/load-image.sh                  # downloads the app for this machine (Intel or ARM)
   cp .env.example .env && chmod 600 .env

4. Fill in .env with a text editor (nano .env):

   DOMAIN=192.168.1.50            # or the DNS name IT gave you
   TLS=internal                    # BioManager makes its own certificate
   POSTGRES_PASSWORD=...           # paste the output of: openssl rand -hex 24
   TZ=America/New_York             # your time zone
   BACKUP_DIR=/opt/biomanager/backups   # better: a folder on a second disk

   If IT gives you a certificate for the name, use TLS=files instead and put it in certs/server.crt and certs/server.key: then skip step 7.
5. Start it:

   docker compose up -d
   docker compose logs app | grep "setup code"

6. Create the admin account. Open https://DOMAIN/register on the server itself and enter the setup code from the last step. The first account is the lab's admin.
7. Trust its certificate on every device, once. Export it: docker compose exec caddy cat /data/caddy/pki/authorities/local/root.crt > biomanager-root.crt and install that file:
   • Mac: double-click it, then in Keychain Access open it and set Trust → Always Trust.
   • Windows: double-click → Install Certificate → Local Machine → Trusted Root Certification Authorities.
   • iPhone/iPad: AirDrop or email it, install the profile under Settings → General → VPN & Device Management, then turn it on under Settings → General → About → Certificate Trust Settings.
   • Android: Settings → Security → Encryption & credentials → Install a certificate → CA certificate.
8. Let people in: allow incoming connections on port 443 in the computer's firewall, and send the lab the address. On Linux, also install the watchdog and weekly updates: sudo host/install.sh (in the deploy folder).

C · A university or department server

Often free · IT does the hard part · campus network and VPN

Many universities give labs a virtual machine on the campus network. Send IT this request:

“We'd like a small Linux VM (Ubuntu 24.04, 2 vCPU, 4 GB RAM, 40 GB disk) with Docker, a DNS name such as biomanager.ourdept.university.edu, a TLS certificate for that name, and port 443 open to the campus network and VPN. It runs BioManager, a lab database, in Docker containers.”

Then follow B from step 3 with TLS=files and IT's certificate in certs/. Nothing needs to be installed on lab devices. If IT offers backups of the VM, take them — they're a welcome extra layer.

D · A cloud VM with Tailscale recommended

Free · about an hour · your lab reaches it from anywhere; no one else can

The server is a virtual machine in the cloud. Tailscale is a private network between your lab's devices: the server has no open ports on the internet at all, yet from any Wi-Fi or phone signal, lab members open it at a normal HTTPS address like https://biomanager.tail1234.ts.net, with a real certificate and nothing to trust by hand.

1. Accounts

1. Create a free Oracle Cloud account (a card is asked for to verify you; Always Free resources are never charged). Pick a home region near you: it can't be changed.
2. Create a free Tailscale account, with a lab or personal Google, Microsoft or GitHub account.
3. On your own computer, download the server bundle, unpack it, and open Biomanager/deploy/cloud-init.yaml in a text editor. You'll paste it in the next step.

2. Create the VM

1. In Oracle Cloud: Compute → Instances → Create instance.
2. Image: Canonical Ubuntu 24.04. Shape: Ampere VM.Standard.A1.Flex, 2 OCPUs and 12 GB (or 4 and 24). If Oracle says it's out of capacity, try again later or pick another availability domain.
3. Networking: a new public subnet, with a public IPv4 address (needed only for the first SSH login).
4. SSH keys: upload your public key (ssh-keygen -t ed25519 makes one; the .pub file is the public half).
5. Advanced options → Management → Initialization script: paste the contents of cloud-init.yaml. It installs Docker, Tailscale and security updates at first boot.
6. Create it and wait a few minutes. Optionally, in Billing, upgrade to Pay As You Go: Always Free stays free, and Oracle then never reclaims an idle free VM.

3. Put it on Tailscale

ssh ubuntu@<the VM's public IP>
ls /var/lib/biomanager-ready          # exists once first-boot set-up has finished
sudo tailscale up --ssh --hostname=biomanager

Open the link it prints and sign in. Then, in the Tailscale admin console:

• Machines → biomanager → ⋯ → Disable key expiry (otherwise it drops off after 180 days);
• DNS: turn on MagicDNS and HTTPS Certificates. Note your tailnet name, like tail1234.ts.net.

From now on, connect with ssh ubuntu@biomanager over Tailscale.

4. Start BioManager

curl -fsSL -o /tmp/biomanager-server.tar.gz \
  https://github.com/gaspolymerase/biomanager/releases/latest/download/biomanager-server.tar.gz
tar -xzf /tmp/biomanager-server.tar.gz -C /opt/biomanager
cd /opt/biomanager/Biomanager/deploy
host/load-image.sh                     # downloads the app for this machine (Intel or ARM)
cp .env.example .env && chmod 600 .env
nano .env

DOMAIN=biomanager.tail1234.ts.net     # biomanager + your tailnet name
TLS=tailscale
COMPOSE_FILE=compose.yaml:compose.tailscale.yaml
POSTGRES_PASSWORD=...                  # openssl rand -hex 24
TZ=America/New_York
BACKUP_DIR=/opt/biomanager/backups

docker compose up -d
docker compose ps                      # wait until app and backup say "healthy"
docker compose logs app | grep "setup code"
sudo host/install.sh                   # watchdog, weekly updates and phone alerts

On a device with Tailscale, open https://DOMAIN/register and create the admin account with the setup code. install.sh prints an ntfy topic: subscribe to it in the ntfy app to hear if the site, the backups or the disk ever need you.

5. Close the door

In Oracle Cloud, open the VM's subnet → Security list and delete the ingress rule for port 22. The server now has no open ports on the internet; SSH and the website both go over Tailscale.

6. Invite the lab

1. Each member installs Tailscale and either joins your tailnet (Users → Invite) or — simpler at any size — you share only the server with their own Tailscale account: Machines → biomanager → Share.
2. They open the address, choose Create account, and you approve them in Manage users.
3. Phones: Tailscale app on, then the BioManager Android app, or Safari → Add to Home Screen on iPhone.

Someone outside the lab who needs a look for a few days doesn't need Tailscale: see guest passes.

E · A cloud VM with your own domain

VM as in D + a domain (about $10–15 a year) · an ordinary address anyone can open

Everyone reaches https://biomanager.yourlab.org with no app at all. The cost of that convenience: the sign-in page is on the open internet. BioManager is built for it — new sign-ups wait for an admin, wrong passwords are throttled, sessions end when a password changes, and a strict content security policy is on — but use strong passwords, and consider sign-in with Google or Microsoft.

1. Buy a domain from a registrar such as Cloudflare, Porkbun or Namecheap (or use a subdomain your department gives you).
2. Create the VM as in D, steps 1–2 (Tailscale is optional; it's still the safest way to SSH in).
3. At the registrar, add a DNS A record: biomanager → the VM's public IP.
4. In the cloud firewall (Oracle: the subnet's security list), allow inbound TCP 80 and 443 from anywhere. Port 80 is needed for Let's Encrypt to issue the certificate.
5. Get the bundle and .env as in D step 4, with:

   DOMAIN=biomanager.yourlab.org
   TLS=acme
   ACME_EMAIL=you@yourlab.org       # Let's Encrypt writes here before a certificate expires

   then docker compose up -d. Caddy gets and renews the certificate by itself.
6. Create the admin account at https://biomanager.yourlab.org/register with the setup code, and run sudo host/install.sh (in the deploy folder).

Other routes

Guest passes: in for a few days, no Tailscale

On a Tailscale server (D), an admin can let someone outside the lab in temporarily. Make a code under Guests in the account menu, then put the server on the internet with Tailscale Funnel: sudo deploy/host/internet-access.sh on (the first time, Tailscale prints a link to allow Funnel). The guest opens https://DOMAIN:8443/guest and enters the code; anyone else there sees only that code page. internet-access.sh off closes it again. See the user guide.

Cloudflare Tunnel

Like E, an ordinary address, but without opening any port: cloudflared on the server connects out to Cloudflare, and Cloudflare Access can require a lab email login before anyone even sees BioManager (free for up to 50 people). It needs a domain on Cloudflare. We haven't packaged it; the AI guide has notes for an assistant setting it up.

Without Docker

BioManager is a Python web app (gunicorn) on PostgreSQL behind any HTTPS proxy, so it runs on a plain server too. Docker is what makes backups, updates and restores one command each, so we recommend it.

After it's running

Set up the lab

The admin's first sign-in opens the set-up survey: tick what the lab keeps and BioManager builds just those databases. See the user guide.

People

Sign-ups wait for approval in Manage users, where admins also make others admin, disable leavers and reset passwords, and give animal-facility staff the Animal care or Facility manager role (what each may do).

Sign-in with Google, Microsoft or your institution

Optional, each one a few lines in deploy/.env and a restart (deploy/README.md in the bundle has the steps). Your institution's own sign-in works through OpenID Connect (Okta, Keycloak, Azure AD, Shibboleth's OIDC plugin): register BioManager with your IT, redirect address https://DOMAIN/auth/institution/callback, and set BIOMANAGER_OIDC_ISSUER, _CLIENT_ID, _CLIENT_SECRET and BIOMANAGER_OIDC_NAME (what the button says). A university that only speaks SAML (InCommon, eduGAIN) comes in through CILogon: BIOMANAGER_CILOGON_CLIENT_ID and _SECRET, and BIOMANAGER_CILOGON_IDP to go straight to your university.

Cage cards with QR codes

On a server, a card's QR code opens that cage on any phone that can reach the server. A Zebra label printer on the lab's network can be sent labels straight from the server (how) when the server can reach it: a server in the cloud can't reach a printer in your lab, unless the printer is on Tailscale too.

Alerts

The ntfy topic from install.sh tells you if the site stops answering, a container stops, the disk fills, or backups stop. deploy/RUNBOOK.md says what to do for each.

Updates

Security fixes for the operating system install nightly, and the containers refresh every Sunday. A new BioManager version is three commands:

cd /opt/biomanager/Biomanager/deploy
docker compose exec backup backup.sh      # a fresh backup first
curl -fsSL -o /tmp/b.tar.gz https://github.com/gaspolymerase/biomanager/releases/latest/download/biomanager-server.tar.gz \
  && tar -xzf /tmp/b.tar.gz -C /opt/biomanager && host/load-image.sh && docker compose up -d --build

Your .env and backups are never in the bundle, so unpacking over it keeps them. The new version brings the database up to date as it starts; every release is tested upgrading a lab made by each earlier one.

Keeping the data safe

A colony's records are years of work. BioManager keeps several independent copies, so no single failure — a deleted VM, a dead disk, a stolen laptop, a bad update — loses them.

Restoring is one command too, and never deletes what it replaces — see deploy/RUNBOOK.md.

Moving from the desktop app to a server

Everything you entered in the app comes along: records, history, IDs. The same steps rebuild a lost server from a lab computer's copy: use the newest .db from its lab-copies/…/db folder instead, and its uploads folder. Do it before the server's first start (the copy goes into an empty database):

1. Quit the app, and copy its data folder (see A) to the server, for example with scp, to /tmp/lab.
2. On the server, in the deploy folder, after host/load-image.sh and filling in .env:

   docker compose up -d db
   docker compose run --rm --no-deps -v /tmp/lab/biomanager.db:/import/lab.db:ro app \
     sh -c 'python scripts/migrate-to-postgres.py /import/lab.db "$DATABASE_URL"'
   docker compose up -d
   docker compose cp /tmp/lab/uploads/. app:/data/uploads/

3. Sign in with your existing account. --dry-run after the script name checks everything first and changes nothing.

On a running server, the master copy can also move to a desktop and back without these steps: an admin hands it over under Settings → Devices, and the desktop gives it back there. While a desktop holds it the server is read only and says where the lab is (Devices).

Set it up with an AI assistant

An AI coding assistant with a terminal (Claude Code, Cursor, Codex and the like) can do most of D or E for you. We keep a guide written for it — the facts, the exact commands, what to check after each step, and the safety rules — at deploy-with-ai.md. Paste this to your assistant:

You stay in charge of the parts only you can do: creating the cloud and Tailscale accounts, approving sign-ins, and typing secrets. The guide tells the assistant to stop and ask at each of those.

Questions

Is a free cloud VM really free?

Oracle's Always Free resources carry no charge. The card is for identity; nothing is billed unless you create paid resources. Free-tier accounts' VMs can be reclaimed when idle for a week; upgrading the account to Pay As You Go stops that and still charges nothing for Always Free resources.

Is Tailscale safe for lab data?

Tailscale connects devices directly with WireGuard encryption; it can't read the traffic. The server is simply invisible to anyone not in your tailnet — a far smaller target than a public sign-in page.

How big does the server need to be?

A lab with tens of thousands of animals uses well under 1 GB of database. The smallest VMs are plenty.

Can we run several labs on one server?

Run one BioManager per lab (each its own folder and domain), or one for a whole facility, where each lab keeps its own databases.

Who can help?

Open an issue with what you're trying and where it stopped.