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_URLthe 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¶
- Create a PostgreSQL database and set
DATABASE_URL,SECRET_KEYand, if not the default,GEOIP_DIR. - Install:
uv sync --no-dev. - Create the schema, and update it after each upgrade:
uv run alembic upgrade head, thenuv run myxo migrate layout.tomlfor the tables where the schedules record their runs. - Create your account:
uv run abilian-analytics user create you@example.com --superuser --generate. It prints a password: change it on your account page. - Run
uv run myxo serve layout.tomlas a service, behind a reverse proxy that terminates HTTPS. It listens onHOSTandPORT(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 updatedownloads both intoGEOIP_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.