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)
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.
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.
Make sure your database is configured to listen to all addresses to work with the containers while running locally. 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.
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.
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 set environment variables manually.
Your database credentials and other environment variables used at runtime are stored in a file when running manually and are taken from the active bash session when using docker-compose.
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=xxxxxxxxxxxxxxxxxxx AUGUR_GITHUB_USERNAME=ExampleUser AUGUR_GITLAB_API_KEY=xxxxxxxxxxxxxxxxxxx AUGUR_GITLAB_USERNAME=ExampleUser AUGUR_DB=postgresql://xxxx:xxxxxxxx@yourhost:5432/yourdb REDIS_CONN_STRING=redis://yourhost:6379 AUGUR_DB_SCHEMA_BUILD=0
Now that you’ve created your config file or are ready to generate it yourself, you’re ready to get going .