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.
Setting up VirtualBox
Go to the official box website to download using this link.
Download VirtualBox for “Windows hosts”.
Click on the downloaded VirtualBox and continue clicking Next with the default options.
Accept the warning for Network Interfaces.
Allow all permissions
Open the VirtualBox by clicking on the Windows desktop icon.
Click “Machine” and then “New”.
Name the Machine. In type select “Linux” and in version select “Ubuntu (64-bits)”.
Choose memory size, then click Next.
Choose “Create a virtual hard disk now” and click Create.
Hard disk file type choose VDI (VirtualBox Disk Image) and click Next.
Storage on physical hard disk choose “Dynamically allocated” and click Next.
Continue with the default options by clicking Next. Your machine will be created.
Start the Machine.
Ubuntu download
Type “Download Ubuntu” in the search bar.
Click download (Prefer LTS version). Ubuntu will be downloaded.
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.
Select Keyboard layout.
Select Installation type “Erase disk and install Ubuntu”.
Enter your details and set a password.
Your Ubuntu will be ready to use in a few minutes.
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.