Augur and Aveloxis: collecting open source metrics at a larger scale

The headline number is a throughput claim, not a feature list

The repository description is blunt about the motivation. When Augur reached a wall, the team made Aveloxis, and the pitch is that 40,000 repositories can be fully collected in three days. The readme restates it as Augur but 40,000 repositories, fully collected, in three days, in Go, with hundreds of issues gone.

That framing tells you what the project is for. Augur is a system for collecting and modelling metrics about open source software, and its original Python implementation was good enough to be widely used but not fast enough to cover large repository populations. Aveloxis is the same model rebuilt for speed, and the primary language of the repository is Go.

The project is hosted under the augurlabs organisation with the Aveloxis code, and the readme points at a separate aveloxis/aveloxis repository as the place to find the project, with the new public site at aveloxis.io. The copyright line credits the University of Missouri, Sean Goggins and Derek Howard, and states that the work is made possible through support of the Sloan Foundation.

The release naming also shows the transition. v1.0.0 was tagged as Aveloxis Rises in May 2026, and the previous versions were v0.92.0 Paladin Penguin and v0.91.0.

The status badges in the readme are the most honest summary of the state: data collection is tested, containers are tested, 8Knot is tested, and the Augur conversion is marked untested.

Two schemas in one database, and that is on purpose

The database design is the part that makes this a migration rather than a fresh install, and the documentation is unusually clear about it.

Aveloxis needs PostgreSQL 14 or newer, and you can point it at an existing Augur database or a fresh one. Either way, Aveloxis creates its own aveloxis_data and aveloxis_ops schemas and does not touch Augur's schemas. The stated reason is full parity: the migrate step creates 108 tables, 84 in aveloxis_data and 24 in aveloxis_ops, matching the Augur schema.

That dual schema approach is the reason an existing Augur deployment can be evaluated without a cutover. You can run the new collector against the same server, let it build its own tables, and compare results before deciding anything. The downside is obvious and also worth stating: you end up carrying both models at once, and any change to the Augur schema is not automatically a change to the Aveloxis schema.

The migration itself is written to be repeatable. All DDL uses CREATE ... IF NOT EXISTS and ON CONFLICT DO NOTHING, so aveloxis migrate is safe to run repeatedly. For a collector that has to be re-run after every schema change during development, that property removes a class of failure.

The go.mod also shows the dependency set, and it is a short one: pgx for PostgreSQL, cobra for the command line, uuid, golang.org/x/net, oauth2 and yaml, plus a very small set of indirect dependencies.

Getting a working instance, in the order the readme gives

The install path is two options, and they differ in one practical way: whether the binary lands on your PATH.

Option 1 installs to your PATH so you can run aveloxis from anywhere, and optionally pulls in analysis tooling for code complexity scanning:

git clone https://github.com/aveloxis/aveloxis.git
cd aveloxis
go mod tidy
go install ./cmd/aveloxis

# Verify it works (binary is now in $GOPATH/bin or $HOME/go/bin):
aveloxis version

# Install optional analysis tools (scc for code complexity):
aveloxis install-tools

If the shell reports aveloxis: command not found, the readme tells you to add Go's bin directory to your PATH.

Option 2 builds in place so the binary stays in the repository directory, and every later command has to use the explicit path instead of the bare command name.

Then the database. Option A reuses an existing Augur database. Option B creates a fresh one in psql as a superuser:

CREATE DATABASE aveloxis;
CREATE USER aveloxis WITH ENCRYPTED PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE aveloxis TO aveloxis;
ALTER DATABASE aveloxis OWNER TO aveloxis;

Option C skips psql entirely with a container:

docker run -d --name aveloxis-db -p 5432:5432 \
  -e POSTGRES_DB=aveloxis \
  -e POSTGRES_USER=aveloxis \
  -e POSTGRES_PASSWORD=aveloxis \
  postgres:16

After that, aveloxis migrate creates the tables, and the readme notes that the collection scheduler needs git on the host for the facade and commit collection phase, along with GitHub or GitLab API tokens carrying read scope.

Three processes, three ports, and a login wall in front of everything

The running system is three processes rather than one, which follows from splitting collection from presentation.

On bare metal, aveloxis start all launches them in the background with logs under ~/.aveloxis, or you can start them one at a time: serve for the collection scheduler, web for the GUI, api for the REST interface. The interfaces are then reachable on three ports, and the readme gives the URLs directly:

open http://localhost:8082          # Web GUI (login, visualizations, comparison)
open http://localhost:8082/monitor  # Collection monitor dashboard (requires login)
open http://localhost:8383/api/v1/health  # REST API

The monitor dashboard at /monitor is the one to watch during a run, since it shows collection progress, and the API health endpoint at /api/v1/health is what a deployment script would poll.

The constraint that will surprise you first is authentication. You need a GitHub OAuth application for the web view login to work, and the readme states plainly that nothing is available without login. GitLab OAuth can be used instead, or both can be configured. For local work the callback URL to register is http://localhost:8082/auth/github/callback, and for GitLab it is http://localhost:8082/auth/gitlab/callback. The homepage URL is described as not important.

So the honest first-run experience is: database, migrations, OAuth application, then a login, and only then a populated interface. A team expecting to browse metrics without registering an OAuth app will not get that.

Containers assume a config file and a healthy database

The Docker and Podman path is the same set of instructions, with podman substituted for docker if that is your runtime.

The compose file starts four services. Postgres runs on postgres:16-alpine with a named volume aveloxis-pgdata that persists across rebuilds, a healthcheck running pg_isready every five seconds with ten retries, and a restart policy of unless-stopped. A migrate service runs the migrations once and exits, which is why the compose file comments describe it as starting four services where one is a run-once job. The serve service runs the collection scheduler with a worker count that defaults to 12 through an environment variable, and exposes a monitoring port at 5555. The web service serves the GUI on 8082, chosen specifically to avoid conflicting with 8Knot on 8080, and the api service serves the REST interface on 8383.

The configuration file is required, not optional, in the container setup. aveloxis.docker.json is mounted read only into the containers, and the example file is aveloxis.docker.example.json in the repository root. A compose file that mounts a file that does not exist will fail at start, so creating it from the example is step one of the container path.

The image build is a two stage Dockerfile. The builder stage starts from golang:1.24-alpine, adds git, and sets GOTOOLCHAIN=auto because go.mod requires Go 1.25 while the published image is 1.24, so the toolchain downloads itself. The binary is built with CGO_ENABLED=0 and stripped with -s -w. The runtime stage is alpine:3.20 with git, ca-certificates and curl, the binary copied to /usr/local/bin/aveloxis, /app and /data as volumes, and ports 5555, 8082 and 8383 exposed.

The compose comments are careful about data loss, noting that only docker compose down -v destroys the database volume.

Optional scanning brings Python into a Go pipeline

The optional extras are worth understanding because they change the shape of your deployment.

ScanCode license and copyright scanning is supported and needs Python 3.10 or newer plus libmagic, and it is installed automatically by aveloxis install-tools. The platform specific instructions are short: brew install libmagic on macOS, sudo apt-get install libmagic1 on Debian and Ubuntu, and sudo yum install file-libs on RHEL and CentOS. pipx is also needed for the scancode installation, along with python-setuptools. Code complexity scanning uses scc, which is also handled by install-tools.

That means a Go binary can spawn a Python based scanner, which is a reasonable design for reusing an existing scanning tool, but it means the container needs both toolchains if you use the scanning path.

The requirements list also carries an honest caveat that is easy to skim past: RHEL and CentOS installations are based on internet searches, because the team does not have access to a machine with those operating systems. So the CentOS and RHEL install lines in the readme are best effort. The same applies to the general posture of the platform list.

The requirements themselves are Go 1.23 or newer, PostgreSQL 14 or newer, git, and GitHub or GitLab API tokens with repo and read scope. A Development Mode section is referenced for people running locally to evaluate, which is the intended path for a trial.

What Augur users should check before committing

The readme includes a comparison section for Augur users, and the conversion path is the open question.

The status badge in the readme marks the Augur conversion as untested while data collection, containers and 8Knot are marked tested. That is the single most important line to read before planning a migration, and it is worth taking at face value rather than assuming the badge is stale.

There is also a note that the work was carried out with the help of Claude Code, with a link to a write-up on how that was used. That context matters for a codebase of this size: it explains the speed of the delivery and it raises the question of how thoroughly the Go implementation has been reviewed against the Python original, particularly in the parts that are hard to test, which is to say the parts that decide whether a metric is computed correctly.

Documentation is published on readthedocs at aveloxis.readthedocs.io. The repository also carries a SECURITY.md, a CODE_OF_CONDUCT.md, an aveloxis-story directory, a scripts directory, a Dockerfile at the root, a .golangci.yml for Go linting, a .pylintrc for the Python side, and an install-scorecard.sh script, which points at the OpenSSF Scorecard practice of publishing supply chain security assessments.

Practically, the evaluation path is a small sample first. Point the collector at a few dozen repositories you know well, check the values against your existing Augur data, and read the monitor dashboard while it runs. The 40,000 repository claim is about throughput, and throughput claims are exactly the kind of thing that holds up on the happy path and needs checking elsewhere.

Editorial conclusion

Adopt Aveloxis if you are running a large scale open source metrics collection and have hit the throughput ceiling of the Python Augur, and you can live with a Go codebase and a parallel schema. Do not adopt it if you are looking for a stable, well trodden tool today, because the Augur conversion itself is marked untested in the project status badges, the web interface requires an OAuth application before anything is visible, and RHEL and CentOS installation guidance is admitted to be based on internet searches. Before you commit, run aveloxis migrate against a copy of your database and compare table counts, and validate one repository end to end through the collection monitor before scheduling a full run.

Frequently asked questions

Official sources

1. augurlabs/augur on GitHub
2. License: MIT
3. Project website
4. README
5. Releases