Getting Started

For the Docker Savvy Who Want to Understand How the Sausage is Made:

Augur provides several Docker images designed to get you started with our software as quickly as possible. They are:

  • augurlabs/augur:backend, our backend data collection and metrics API

  • augurlabs/augur:frontend, our metrics visualization frontend (Experimental, will be replaced in the future)

Warning

The frontend is very out of date and will likely not work. It is still available, but it is in the process of being replaced with an entirely new frontend so the old frontend is not being actively fixed.

  • augurlabs/augur:database, an empty PostgreSQL database with the Augur schema installed

  • augurlabs/augur:test_data, a PostgreSQL database loaded with the data used in our testing environment

If you’re not familiar with Docker, their starting guide is a great resource.

The rest of this section of the documentation assumes you have a working installation of Docker as well as some familiarity with basic Docker concepts and a few basic Docker and Docker,Compose commands.

If you are less familiar with Docker, or experience issues you cannot resolve attempting our “quick start”, please follow the instructions in this section, and the next few pages, to set up your environment.

Credentials

Before you get started with Docker, you’ll need to set up a PostgreSQL instance either locally or using a remote host. Alternatively, you can also set up the database within a docker container either manually or through the script but this is not recommended.

Note

Make sure your database is configured to listen to all addresses to work with the containers. These settings can be edited in your postgresql.conf. Additionally, edit the bottom section of your pg_hba.conf file with:

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host      all             all             0.0.0.0/0               md5

If you’re interested solely in data collection, we recommend using our test data with the Docker Compose script. This will start up the backend and frontend containers simultaneously, well as an optional database container; however, if you are looking to collect data long term, we strongly suggest setting up a persistent database instance; you can find instructions for doing so here. Remember to save off the credentials for your newly minted database; you’ll need them shortly.

If you don’t care if your data doesn’t get persisted or are doing local development, you can use the database containers we provide.

Warning

Using a Docker container as a production database is not recommended. You have been warned!

If you’re more interested in doing local development, we recommend using our Docker testing environment image - more on that later.

Configuration File

Besides a database instance, you will also need a GitHub Access Token (repo and all read scopes except enterprise). This is required for all Docker users.

First, you’ll need to clone the repository. In your terminal, run:

$ git clone https://github.com/chaoss/augur.git
$ cd augur/

Now that you’ve got your external database credentials (if you are using one) and your access token, we’ll need to use to docker setup script or set environment variables manually.

Your database credentials and other environment variables used at runtime are stored in a file called docker_env.txt. This file determines the database credentials, the GitHub API key, and whether or not to build the database schema.

If you do not want to use the script (not recommended) you can provide your own docker_env.txt to pull from. The file should have the below format and set all the variables to some value.

AUGUR_GITHUB_API_KEY=your_key_here
AUGUR_DB_SCHEMA_BUILD=0
AUGUR_DB_HOST=xx.xxx.xxx.xxx
AUGUR_DB_NAME=augur
AUGUR_DB_PORT=5432
AUGUR_DB_USER=augur
AUGUR_DB_PASSWORD=somePassword

Note

If you’re using the test_data image instead of your database image, you’ll need to add AUGUR_DB_NAME=test_data to your docker_env.txt to override the default database image name. This is taken care of for you if you use the script.

Now that you’ve created your config file or are ready to generate it yourself, you’re ready to get going. If you’re doing data collection or just want to try out Augur, you’ll want to use the docker-setup.sh script. If you’re installing Augur for local development, we recommend using the more fine-grained Docker commands to build and run the containers individually. Using Docker Compose or the script is still a good way to try out the system as a whole before you start developing, and it doesn’t hurt to know either!

Note

Linux is currently the only supported platform for the script. Docker is slightly different on macOS. Additionally, the script uses a network alias for local connections which is done differently for macOS. The script will setup the alias for macOS correctly but it is untested for macOS and can be unpredictable.

Docker Setup Script

Note

It may take a while to download/build the docker containers depending on your internet/computer.

First, start the script in the augur directory using sudo ./docker-setup.sh

Answer the prompt to select the type of deployment to use:

  1. Deploy the backend using docker connected to a non-docker database.

    This option lets you deploy the backend using your database whether local or remote.

  2. Deploy the backend and database together in docker containers.

    This option lets you deploy the backend and database together as a pure docker deployment starting from an empty database.

  3. Deploy the backend, and database together in docker containers using premade test data

    This option lets you deploy the backend and database together as a pure docker environment with pregenerated testing data to use. This option is great for trying out augur.

Deploying the backend using docker connected to a non-docker database

Answer yes when the script prompts you for your database credentials if you did not manually generate the docker_env.txt. They will be saved locally and will persist if left unchanged.

Warning

Make sure to specify localhost or 10.254.254.254 if the database is set up locally.

The script will then prompt you to ask whether or not to build a schema on the database. The default option is “no,” only select yes if the database is without an existing schema.

If the containers deploy, the console output will switch to a monitor of the state of the twin containers, with a monitor of both of their console output below.

A keyboard interrupt will stop the containers and the script gives you the option of saving the console output to a log file.

Deploy the backend and database together in docker containers. With and without test data

If you have run the containers before and have already generated your environment variables the script should remember your github api key. Only change it if it is not the intended api key to use.

The containers should then deploy, switching to a console feed along with the process state of each docker container.