Logbook for scuba divers: multi-gas dives, dive-computer imports, trips, gear

A dive log built to outlive every vendor. Your dives, your data — vendor exports in, open formats out, everything in one click. Yours to self-host, and this repository is the install.

OpenDiving is an open-source logbook for scuba divers, recreational and technical: log dives with multi-tank gas mixtures, import them straight from your dive computer's export files — full depth/temperature/tank-pressure profile, the heart rate where the computer measured one, deco ceiling, the readouts the computer itself computed and dive events included — group them into trips, and keep your gear service history and c-cards in one place.

Cloud dive logs come and go — Movescount, Deepblu, Diveboard — and when they go, years of dive history go with them. OpenDiving is built on a different premise: the app is AGPL-licensed, every dive-computer file you upload to a dive is kept with it, downloadable at any time, and one click takes everything out in open formats. Self-hosting is what turns that from a promise into a guarantee — the whole stack is yours to run, on your own machine and your own Postgres, so no shutdown, acquisition, or paywall can ever take your logbook with it.

One instance is run by the project itself: opendiving.app, a closed beta with a waitlist. It is the same code at the same release as an install from this repository — the difference is only who operates it, and running your own copy is still the version of this with nobody to trust but yourself.

mkdir opendiving && cd opendiving curl -LO https://github.com/opendiving/opendiving/releases/latest/download/install.sh less install.sh # it is about to write your .env bash install.sh

It checks Docker, fetches the bundle, generates the secrets, asks for the few values only you know, and stops — leaving you a .env and the docker compose up -d to run. Four commands and an editor do the same thing by hand: install guide.

Point your domain's DNS record at the machine before starting the stack — the bundled Caddy asks Let's Encrypt for a certificate as it starts, and it can only get one for a name that already resolves. Then open https://your-domain, press Sign In, ask for a link, and the first account to sign in is yours — it carries the operator's rights. A new install is invite-only, so everybody after you gets in by an invitation, sent to their address or handed over as a member's invite link and its QR code; REGISTRATION_MODE=open is the other setting, and the configuration guide has both.

That is the whole product: the web app, the API and its worker, PostgreSQL, Redis, and Caddy terminating TLS with a certificate it fetches itself — plus, once you switch it on, a renderer that draws the maps behind the dive, trip and dive site cards and at the head of their pages. Nothing is built — every image is pulled, prebuilt for amd64 and arm64, so a Raspberry Pi runs the same bytes as a VPS. Migrations apply themselves on startup, so an upgrade is docker compose pull && docker compose up -d. A backup is two artifacts: a pg_dump and a copy of the uploaded files, which are on a volume beside the stack unless you point the API at an object store instead.

Read the install guide first if you'd rather know what you're getting into — what you need, what the six values are, and what each container does.

Dive logging — times, depths, duration, water and air temperature, visibility, water type, altitude, current, waves, weather, weight, notes, and any number of gas mixtures (O₂/He, start/end pressures) per dive, with whether you went in from the shore, a pier, a pool or a boat and the boat's name. Say what kind of dive it was, from open circuit to freediving, rate it out of five and tag it in your own words — tag it survey when you recorded every species you could identify, the spelling other readers of your log look for; the dive list filters by tag or type and sorts by rating, and Settings renames or deletes a tag. A dive can span multiple dive sites, in order, because drift dives happen.

Technical diving — trimix and nitrox mixes get derived gas names and per-mix MOD at your ppO₂ limit, plus END/EAD; the profile chart shades the deco ceiling, plots the computer's own NDL, TTS, ppO₂, CNS and gradient factors, draws the heart rate it measured in a row of its own — the profile card states its maximum and average — and marks dive events; each recording says the mode it ran in and the decompression model behind those numbers; CNS/OTU oxygen exposure and surface pressure are kept from imports, per-cylinder ppO₂ limits and gas roles included.

Dive-computer import — upload one dive's file in any format Logbook import below reads and the form pre-fills itself, while a file holding several dives, or one file carrying two computers' records of a dive, goes through that import instead. Each file lands on a recording, one per device that recorded the dive: two computers on one dive are two recordings, and one computer's JSON beside its FIT is two files of one recording, each filling what the other left blank. Every file you upload stays with the recording it came from and can be re-downloaded any time, and the per-sample profile is extracted and charted per recording, with a switcher when a dive has more than one. A computer that chopped one dive in half logs it as two dives, and Merge folds them back into one.

Air consumption — SAC and RMV derived automatically, including a per-tank breakdown across recorded gas switches, with a consumption trend on the Home page.

Trips and species — group dives into a liveaboard or a holiday week; track what you saw, with how many you counted or a band — few, many, abundant — and a note on each.

Dive sites — your own site list: the other names a site goes by, the depths it is dived at, its water, its altitude and how you get in, your own tags, and its OpenStreetMap or Wikidata entry when you pick it from the built-in catalogue of named sites. A site's page sums up your dives there — how many, the last and the deepest, the species you saw and your average rating — beside every dive logged at it, and a dive logged there starts from its water, altitude and entry. The list sorts by name, by dives or by the last dive, and filters by a tag.

Gear tracking — equipment with per-item dive counts and dive time, groupable into sets you attach to a dive in one click; a cylinder records its volume, working pressure and material once, and a dive's tank links it. Plus service schedules by months, dives or hours of diving, with due-soon reminders on the Home page and by email.

Certifications — photos of your c-cards on hand at the dive shop, without digging out the plastic, and an email when a card or one of your insurance policies comes within 90 days of expiring, and again when it does.

Check-in — the details a dive shop asks for at the desk, kept once: a portrait cropped like a passport photo, date of birth, phone, the email you choose to give out, which need not be the one you sign in with, your emergency contacts in the order to call them, and your insurance policies. One page gathers them with your c-cards, dive count, max depth and last dive, and prints — your browser's save-as-PDF is the copy for a desk with no signal — or shares as a link and a QR code the desk opens on its own phone, for a day or until you revoke it.

Contacts — the dive centers, shops, schools, clubs and places you stayed, each kept once and picked from a list rather than typed again: for a dive, a course, a c-card, a gear service or a part of a trip. A UDDF file's dive bases, shops and accommodation arrive as contacts.

People — who you dived, travelled and trained with: buddies, guides, instructors, fellow students, whoever came along. Each is kept once and picked from a list, with the role they had on that dive, trip or course, and a course's or a c-card's instructor is one of them. Link one to their account on the same instance by its username, if you choose, and you see that account's current username beside the name and nothing else of theirs; they are not told. A UDDF or Subsurface file's buddies and dive guides arrive as people.

Full export — one click takes everything out in open formats: a DiveJSON document — the open dive-log interchange format this project publishes and implements — a UDDF document other programs import, a CSV for a spreadsheet, or a complete archive carrying all three, your unfinished dive drafts, every dive-computer file you uploaded, every c-card image you stored, and your profile picture and portrait. A data-ownership log without an exit door is a contradiction.

Logbook import — and the door swings both ways: bring a whole logbook in from a DiveJSON document, a full archive, a UDDF file, a Subsurface .ssrf, a FIT file, a Suunto app JSON export, a Shearwater Cloud database export holding every dive of the account or its XML export of one dive, a Suunto DM5 XML export, or a zip of any of them — any number of files at once, in any mix, so a watch's whole folder of exports arrives in one go. A computer's two exports of one dive become one dive with both files, and a file converted from another format that is one dive is kept on the dive it becomes; a logbook of several dives, or a DiveJSON document, arrives without its file. You see what each file was read as and a row for every dive it becomes — new, already here, brought back from deletion, gaining a file, or skipped and why — before anything is written, and under each dive what its files did not record, what the import worked out, and which of the dive's values it left out. Records you already have are matched rather than duplicated, a dive you deleted comes back under the identifier it had, and the full archive restores the files it carries too. An exit door you cannot walk back through is only half of owning your data.

Year in review — each January, an email with the year before in figures: dives and time underwater, the deepest and longest, dive sites, and species with the ones you saw for the first time.

Passwordless sign-in — email magic links, a six-digit code, passkeys, or Google. No passwords stored, ever.

Dark mode and responsive — works on the boat, in the dive shop, and on your desk.

Installs like an app — add it to a phone's home screen from the browser's install or share menu (on iOS 16.4 and later, Safari's Share → Add to Home Screen), and it opens in its own window on your Home page.

Planned

Roughly in priority order — contributions welcome:

The install, and the documentation for running it. Three files — docker-compose.yml, Caddyfile and example.env — plus install.sh, which fetches them and writes the .env, plus docs/. Every release publishes all four as assets, which is what the curl line above fetches, and a release here is the product's release: the version that both images are tagged with, verified to exist for both architectures before the notes are ever written.

scripts/ and .github/workflows/ hold the release machinery — what picks the one version all three repositories are tagged with, and the single dispatch that cuts the release across them. It is machinery rather than anything an install downloads.

Each carries its own CONTRIBUTING.md with its setup, its checks and its house rules, and its own DECISIONS.md recording the non-obvious choices already made. Working on the app means working in one of those; this repository is where the two of them become something you can install.

Issues and pull requests are welcome — a typo in the install guide as much as a new importer. Open an issue first for anything large, so the shape can be agreed before the work. CONTRIBUTING.md is the rest of it: what a change here looks like, how to verify a change to the bundle locally without a release existing, and how a release is cut.

An issue about installing, upgrading, backing up or configuring an instance belongs here. A bug in the app itself belongs in opendiving-api or opendiving-web; if you can't tell which, open it here and it will b