v0.1.0

The first installable release of OpenAnalytics: privacy-first web analytics you
run on your own hardware, under AGPL-3.0.

Nothing to do by hand. There is no earlier version to upgrade from, no
migration to run yourself, and no setting that changes meaning. If you have been
running from main, see Coming from main at the end.

Install

Eight images are published to ghcr.io/openlabs-so/openanalytics, so installing
is a pull. A fresh host is a few minutes and needs no toolchain on it.

Point four names at the host first. Certificates are issued on the first boot
and issuance fails without them, half an hour later and nowhere near the cause:

app.example.com   api.example.com   c.example.com   rt.example.com

git clone https://github.com/OpenLabs-so/openanalytics
cd openanalytics
git checkout v0.1.0
cd infra/selfhost
./generate-secrets.sh --domain example.com --email you@example.com --with-geoip

The generator writes defaults that build the images here. Point the two at this
release instead:

# infra/selfhost/.env
OA_IMAGE_REPO=ghcr.io/openlabs-so/openanalytics
OA_IMAGE_TAG=v0.1.0

docker compose pull && docker compose up -d

Then open https://app.example.com. A deployment nobody has signed into offers
to create the first account rather than asking you to sign in, and that offer
closes permanently the moment one account exists. Do it immediately: your four
DNS records are public.

SELF-HOSTING.md
is the full guide, including every secret and every failure mode.

What you get

Page views, custom and attribute-driven events, sessions, Core Web Vitals,
funnels, per-site retention, embeddable widgets, public share links, revenue
analytics from your own Stripe account, CSV and JSON import and export, an MCP
server, and a CLI.

No cookies, no fingerprinting, no cross-site identifiers. Visitor identity is a
salted hash that rotates at UTC midnight and differs on every site, raw IP
addresses are never stored, and Do Not Track and Global Privacy Control are
honoured at the collector before anything is written. Geolocation is resolved
against a database on your own disk, so no lookup leaves the host.

Mail and the model provider are configured from the dashboard, encrypted at
rest, with a test send that reports what the relay actually said. A fresh
install can invite people without an operator opening a shell.

From here on: upgrading, and going back

./upgrade.sh moves between releases. It takes a snapshot first, because that
snapshot is the only way back: migrations do not go down. Going back is
./rollback.sh --to <snapshot>, and a restore discards everything recorded
since the upgrade.

The script states all three costs before it does anything, not at rollback time
when you no longer have a choice: downtime while the collector is refusing
events, the data a restore would lose, and the disk a full compressed copy takes.

That path is proven in CI rather than asserted. A job writes a row into Postgres
and into ClickHouse, takes a snapshot, destroys the row, restores, and reads it
back.

No reverse migrations is a decision, not a gap. A reverse migration is code that
runs once, in an emergency, having never run before.

Limits worth knowing before you start

• amd64 only. Cross-building eight images under emulation puts a release out
  of reach of an ordinary runner. On arm64, build from source instead:
  ./upgrade.sh --from-source, or docker compose up -d --build on a first
  install. Add swap on a 4 GB box; the build wants more memory than the box has
  spare while the stores are running.
• The GeoIP database is opt-in. --with-geoip fetches DB-IP City Lite, a
  60 MB download that unpacks to about 125 MB. A failed download leaves a
  working install with country-level data off rather than a broken one.

Coming from main

Check out the tag rather than pointing your existing tree at the images. The
compose file, the env templates and the migrations ship with the images, so
the checkout and the image tag are one version or the install is a
configuration nobody has tested.

.env no longer carries OA_PUBLIC_API_URL, OA_PUBLIC_COLLECTOR_URL or
OA_PUBLIC_REALTIME_URL. They were build arguments and are now ordinary runtime
configuration in env/web.env, which is what lets one published dashboard image
serve any deployment. An existing .env keeps working; the three variables are
simply unused.

What a version number means here

RELEASING.md
says what a patch, a minor and a major cost you as an operator, which is the
question a version number is usually asked.

---

Nothing in this release changes ingest, the schema or the tracker. It is
packaging: the software was already here, and now it installs.