Skip to content

Deploy

Abilian Analytics needs a PostgreSQL database, a SECRET_KEY, and a reverse proxy that terminates HTTPS. One process serves the web app and runs the background jobs: GeoIP updates, alerts, monitoring checks, email reports. Every setting is an environment variable: see configuration.

On Hop3

The repository has a hop3.toml that declares everything:

  • the app's one process, myxo serve layout.toml: the web app, and the background jobs on their schedules (GeoIP updates, with the databases in a volume kept across deploys; alerts; monitoring checks; email reports);
  • a PostgreSQL addon, which sets the DATABASE_URL the app requires;
  • a generated SECRET_KEY;
  • the database migrations, run before each start;
  • a health check on /health.

Deploy with make deploy (that is, hop3 deploy). For a first deployment, follow the runbook: it goes from an empty server to production, the import of Umami's and Matomo's history included.

Elsewhere

  1. Create a PostgreSQL database and set DATABASE_URL, SECRET_KEY and, if not the default, GEOIP_DIR.
  2. Install: uv sync --no-dev.
  3. Create the schema, and update it after each upgrade: uv run alembic upgrade head, then uv run myxo migrate layout.toml for the tables where the schedules record their runs.
  4. Create your account: uv run abilian-analytics user create you@example.com --superuser --generate. It prints a password: change it on your account page.
  5. Run uv run myxo serve layout.toml as a service, behind a reverse proxy that terminates HTTPS. It listens on HOST and PORT (127.0.0.1 and 5000 by default), and runs the background jobs: the GeoIP databases download at the first start.

The process runs on Myxo, which keeps the schedules in the app's database: each job runs once per period, wherever the process restarts. A job that fails is logged, with its traceback, and runs again at its next period; the other jobs go on.

The client's address

The reverse proxy must append the client's address to X-Forwarded-For (nginx: proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;). The app trusts only the right-most entry of that header, the one your proxy adds. With a second proxy in front, such as a CDN, the addresses it records would be the CDN's.

GeoIP databases

Countries and networks come from DB-IP's free "Lite" databases (country and ASN), published monthly under the Creative Commons Attribution 4.0 licence. The app's pages credit DB-IP in their footer, as the licence asks.

  • abilian-analytics geoip update downloads both into GEOIP_DIR; with --max-age 7, only those missing or more than a week old. A download is checked before it replaces a database, so a failed one leaves the old one in place.
  • The app's background jobs do the same daily, the first time at the first start, and download a database again once it is a week old.
  • The app reopens a database when its file changes: no restart is needed.

Without them, visits have no country or network, so blocked countries and hosting networks aren't filtered. Administration → Instance health says how old they are.

Backups

Everything is in the database. Back it up daily, for instance with pg_dump --format=custom, and try a restore once.

Upgrading

Pull the new version and run alembic upgrade head before starting the app. On Hop3, deploying does both.