Skip to content

Open source metrics

Jump to bottom
Sam Cunliffe edited this page Nov 3, 2025 · 4 revisions

  1. We've deployed GitHub Community Project's org-metrics-dashboard with some @neuroinformatics-unit improvements to display some simple metrics about the open-source repos in @UCL and @UCL-ARC (@UCL-ISD currently broken).

    • Deployed by GitHub actions on a cron.
    • Publically available here.

  2. We have experimented with both CHAOSS metrics dashboards: Augur/8Knot and GrimoireLab. Here are our deployment notes for deploying them for the UCL repositories on ARC systems (i.e. Condenser).

Common

Requirements

  • Docker, including docker compose (on Linux distributions it may be a separate package than base Docker)
  • Git
  • Some kind of server
    • We've hosted on Mosès Mac and on Condenser.
    • For Condenser: connect to the UCL VPN and follow the Condenser documentation to create a VM with ~8 Cores, ~16GB RAM, and ~100GB volume. We've used Ubuntu, but Almalinux would probably work too.

Augur & 8Knot

Deployment

Augur

We use the Docker compose deployment strategy. Clone the Git repository and enter the directory:

git clone https://github.com/UCL-ARC/augur
cd augur

Create the .env file as explained in the documentation, populate the files repos.csv and repo_groups.csv as appropriate (see the docs about the commands augur db add-repo-groups and augur db add-repos for more information) and then you can start the deployment with

docker compose up --build

The Augur dashboard should be accessible on port 5002 (e.g. http://localhost:5002), while the Flower dashboard for debugging the data collection is on port 5555 (e.g. http://localhost:5555).

Restart from scratch

If you need to restart from scratch, take down the runtime with Ctrl+Ctrl in the shell running the command docker compose up, in any case in the top-level directory of the Augur repo run also the command

docker compose down

This however, won't remove the volume where the database was saved, to do that run the command

docker volume rm augur_augurpostgres

After this, you can run again

docker compose up --build

to rebuild the runtime. If you want to rebuild from a complete clean state, ignoring Docker's build cache you can use instead

docker compose build --no-cache
docker compose up

8Knot

Also in this case we'll use the Docker compose deployment strategy, connecting to the Augur deployment used for the backedn. Clone the Git repository and enter the directory:

git clone https://github.com/UCL-ARC/8Knot
cd 8Knot

Create the .env file as explained in the README and then you can start the runtime with

docker compose up --build --scale worker-query=2 --scale worker-callback=2

The 8Knot dashboard should be accessible on port 8080 (e.g. http://localhost:8080).

Restart from scratch

8Knot has a cache of the postgres database, if you want to restart the deployment from scratch you need to delete the corresponding volume. It doesn't appear to have a name, so after shutting down the 8Knot runtime (but keep Augur up to keep the volumes alive!) with

docker compose down

and delete the postgres cache volume with

docker volume rm 8knot_postgres-cache

and then you can restart the deployment with

docker compose up --build --scale worker-query=2 --scale worker-callback=2

If you have the impression the postgres cache is still stale, there's an unnamed volume which is used, to remove that you have to either figure out its label, or you can prune all the unused volume with

docker volume prune

and rebuild the runtime once again.

Troubleshooting

Entering the running containers

If you need to enter the running containers for debugging purposes, in the directory containing the docker compose YAML filw declaring the container you want to enter, run the command

docker compose exec augur bash

where augur is the name of the container you want to attach to (we used here the name of the main Augur container as an example).

Interacting with the Augur database

GUI

If you have access to a screen connected to the machine hosting the service, or you can forward the port on which the database is served, you may find it useful to use GUIs for interacting with the Augur database. There are multiple graphical interfaces for accessing a Postgres database, one that we found nice is DBeaver. After installing it, start DBeaver and create a new connection with the following properties:

  • host: localhost
  • port: 5432
  • database: augur (or what you put in your .env)
  • username: augur (or what you put in your .env)
  • password: what you put in your .env

and then connect. Now you should be able to explore the augur database.

If you're running the deployment on a remote machine, you will need to forward the 5432 port with a command like

ssh -L 5432:127.0.0.1:5432 <REMOTE_HOST>

where <REMOTE_HOST> is the remote host where the deployment is running.

Terminal

Enter the augur container as explained above and run the command

psql -U augur -h augur-db -p 5432 -d augur

You will be prompted for the password, which you can find in your .env file, and then in the postgres shell you can run \c augur to connect to the augur database.

Check status of API keys

To check the number of queries still available for the API keys available in the Augur deployment, you can run the command

augur github api-keys

inside the augur container, see the section above for how to access it.

Note

To run the augur command your working directory must be /augur.

Add GitHub tokens

Replace existing GitHub tokens

There a simple command to replace all the GitHub tokens with a new: enter inside the augur container in the Augur directory and use the command augur config

augur config init --github-api-key ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

where ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX is the new GitHub token.

Note

To run the augur command your working directory must be /augur.

Note

This command will erase all previous tokens, is not good for simply adding a new one.

Add multiple tokens

Alternatively, you can add more keys to your Augur deployment, to potentially speed up data collection in case your key is running out of queries (check it with augur github api-keys as explained above) by entering the augur container and connect to the database (psql -U augur -h augur-db -p 5432 -d augur) and run commands like

INSERT INTO "augur_operations"."worker_oauth" ("oauth_id", "name", "consumer_key", "consumer_secret", "access_token", "access_token_secret", "repo_directory", "platform") VALUES (1018, 'label1', '0', '0', 'ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', '0', NULL, 'github');
INSERT INTO "augur_operations"."worker_oauth" ("oauth_id", "name", "consumer_key", "consumer_secret", "access_token", "access_token_secret", "repo_directory", "platform") VALUES (1019, 'label2', '0', '0', 'ghp_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY', '0', NULL, 'github');
INSERT INTO "augur_operations"."worker_oauth" ("oauth_id", "name", "consumer_key", "consumer_secret", "access_token", "access_token_secret", "repo_directory", "platform") VALUES (1020, 'label3', '0', '0', 'ghp_ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ', '0', NULL, 'github');

You'll need to replace the label*s with labels for the tokens, and the ghp_*s with the GitHub tokens. You may also need to replace the IDs 1018, 1019, 1020 if there are already tokens with those IDs in the table.

GrimoireLab

We follow the getting started instructions and similar to Augur and 8Knot, use Docker compose.

We have a fork to keep track of what's actually deployed. If you make changes, please keep the fork up-to-date with both upstream and the setup.

git clone https://github.com/UCL-ARC/grimoirelab
cd grimoirelab

GrimoireLab is controlled by two files: the setup.cfg and the projects.json. The projects.json contains around 1k GitHub URLs for repos collected at the time of issue open-source/#13. It's a static list so you may need to update it or remove old projects. If you want to debug, @UCL/STIR and @neuroinformatics-unit/movement are good test candidates as they are actively developed and STIR has a long history.

setup.cfg contains the GitHub API access token under the [GitHub] heading. It only accepts one API token and as far as we can see there's no way to have more than one. The token only needs public_repo permission but it needs to be a classic (not fine-grained) access token.

Clone this wiki locally