Quickstart

Get going fast! Intended for folks familiar with setting up DevOps environments. These instructions were tested using Ubuntu 20.04. Ubuntu 18x is no longer supported because the versions of Python3 available on it are not current.

Complete installation instructions with more complete explanations are located in our “Getting Started” section.

Setting up VirtualBox

  • Go to the official box website to download using this link.

  • Download VirtualBox for “Windows hosts”.

_images/A2.png
  • Click on the downloaded VirtualBox and continue clicking Next with the default options.

_images/A3.png
  • Accept the warning for Network Interfaces.

_images/A5.png
  • Allow all permissions

_images/A4.png
  • Open the VirtualBox by clicking on the Windows desktop icon.

  • Click “Machine” and then “New”.

_images/A6.png
  • Name the Machine. In type select “Linux” and in version select “Ubuntu (64-bits)”.

_images/A7.png _images/A8.png
  • Choose memory size, then click Next.

_images/A9.png
  • Choose “Create a virtual hard disk now” and click Create.

_images/A10.png
  • Hard disk file type choose VDI (VirtualBox Disk Image) and click Next.

_images/A11.png
  • Storage on physical hard disk choose “Dynamically allocated” and click Next.

_images/A12.png
  • Continue with the default options by clicking Next. Your machine will be created.

  • Start the Machine.

_images/A13.png

Ubuntu download

  • Type “Download Ubuntu” in the search bar.

  • Click download (Prefer LTS version). Ubuntu will be downloaded.

_images/A14.png

Installing Ubuntu in VirtualBox

  • Open the machine which we have created earlier.

  • Now in the pop-up, click on the disk image where you have downloaded your Ubuntu and click on finish.

  • In the welcome window select Install Ubuntu and move forward with the default options.

_images/Af.png
  • Select Keyboard layout.

  • Select Installation type “Erase disk and install Ubuntu”.

_images/Ad.png
  • Enter your details and set a password.

_images/Ac.png _images/Ab.png
  • Your Ubuntu will be ready to use in a few minutes.

_images/Aa.png

PostgreSQL Installation

  • Gain access to an Ubuntu 18.04 or later environment and install PostgreSQL. Ubuntu 20.04 is recommended because its long-term support (LTS) window is longer.

sudo apt update
sudo apt upgrade
sudo apt install software-properties-common
sudo apt install python3-dev
sudo apt install postgresql postgresql-contrib postgresql-client
sudo apt install build-essential
  • Create a PostgreSQL database for Augur to use

$ sudo service postgresql start
$ sudo su -
$ su - postgres
$ psql

Then, once you’ve connected to your PostgreSQL instance:

postgres=# CREATE DATABASE augur;
postgres=# CREATE USER augur WITH ENCRYPTED PASSWORD 'password';
postgres=# GRANT ALL PRIVILEGES ON DATABASE augur TO augur;

Install RabbitMQ

To set up rabbitmq for augur you must install it with the relevant package manager for your distro. You can find more info on how to install rabbitmq here.

After installation, you must also set up your rabbitmq instance by running the below commands:

sudo rabbitmqctl add_user augur password123

sudo rabbitmqctl add_vhost augur_vhost

sudo rabbitmqctl set_user_tags augur augurTag

sudo rabbitmqctl set_permissions -p augur_vhost augur ".*" ".*" ".*"

Note

it is important to have a static hostname when using rabbitmq as it uses hostname to communicate with nodes.

Then, start rabbitmq server with .. code-block:: bash

sudo systemctl start rabbitmq.service

If your setup of rabbitmq is successful your broker url should look like this:

broker_url = ‘amqp://augur:password123@localhost:5672/augur_vhost’

During installation you will be prompted for this broker url.

Install Go

Two of Augur’s workers use the Go programming language, which needs to be installed on your computer. Snap is the easiest way to install Go. If Snap does not work for you, see instructions here: https://www.digitalocean.com/community/tutorials/how-to-install-go-on-ubuntu-20-04

sudo apt update
sudo apt install snapd
sudo snap install go --classic

Incase you encounter any problem following the above commands, try doing these first:

sudo apt-get update && sudo apt-get install -yqq daemonize dbus-user-session fontconfig
sudo daemonize /usr/bin/unshare --fork --pid --mount-proc /lib/systemd/systemd --system-unit=basic.target
exec sudo nsenter -t $(pidof systemd) -a su - $LOGNAME
snap version

If the last command returns successfully, you can try installing Go again using either of the two options above.

Python Virtual Environment Configuration

  • Set up a Python virtual environment (Python 3.8 and above are now required. Python 3.9 and python 3.10 work as well, though we have tested Python 3.9 on more platforms.)

  • Clone and install Augur as a regular user.

# Ensure you are logged in as your user on Github and change the "<YOUR_GITHUB_USERNAME>" to your Github username (e.g. "sean")
git clone https://github.com/<YOUR_GITHUB_USERNAME>/augur.git
cd augur/
sudo apt install make
sudo apt-get install python3-venv
python3 -m venv $HOME/.virtualenvs/augur_env
source $HOME/.virtualenvs/augur_env/bin/activate
sudo apt install python-pip-whl
sudo apt install python3-pip
sudo apt install pythonpy
python -m pip install --upgrade pip
make install-dev {Follow prompts. You will need database credentials, a file location for cloned repositories, a GitHub Token, and a GitLab token.}
  • Seven sample repositories will load by default. You can delete them if you want to use your repositories by deleting records from the repo table first, then deleting the records from the repo_groups table.

augur --help
augur db --help
augur backend --help

Loading Repositories

The commands for loading repos are:

augur db add-github-org
augur db add-repo-groups
augur db add-repos

We recommend that you test your instance using 50 or fewer repositories before undertaking a more substantial data collection. When you do take on more collection, you can “collect data faster” by adding additional tokens to the worker_oauth table in the augur_operations schema and increasing the number of workers for the pull request and GitHub worker blocks in the augur.config.json file that generates at install.