Instructions on how to setup a machine to run this project.
3.1. Basic Setup Instructions¶
This project now uses docker-compose as it’s main form of setup. You can use the following steps to get a sample server up and going
- Install [docker/docker-compose.](https://docs.docker.com/compose/install/)
- Clone this repository.
- Make a copy of
.env(yes, it starts with a dot).
- Edit the new
.envfile, filling in new values for the first block of uncommented lines. Other lines can be safely ignored as they only provide additional functionality.
docker-compose up(possibly using
- Once up, you’ll need to run the following commands to collect all the static files (to be run any time after you alter the static files), to load in an initial hunt to pacify some of the display logic (to be run only once), and to create a new admin user (follow the prompts).
docker-compose exec app python3 /code/manage.py collectstatic --noinput docker-compose exec app python3 /code/manage.py loaddata initial_hunt docker-compose exec app python3 /code/manage.py createsuperuser
- You should now have the server running on a newly created VM, accessible via
(http://localhost). The repository you cloned has been
linked into the VM by docker, so any changes made to the repository on the
host system should show up automatically. (A
docker-compose restartmay be needed for some changes to take effect)
3.1.1. Setup details¶
The basic instructions above bring up the following docker containers:
- The postgres database with the settings specified in the .env file. Data
is retained across container restarts in
- A redis server for caching and task management. Data is stored in
- The Django application running using gunicorn on port 8000.
- A Huey consumer for scheduled tasks.
- An apache server to proxy web requests to the “app” container and serve the static files. By default, this container serves web requests using plain HTTP over port 80. See the “Extra Setup Instructions” for details on setting up SSL.
There are also 2 volumes shared by a number of the containers that hold static files and media files and will persist across docker restarts.
3.2. Extra Setup Instructions¶
In addition to the basic instructions above, there are a few additional setup
options available. These additional options are provided via “override files”
that override various parts of the docker compose logic. You can enable which
override files are being used by setting the
COMPOSE_FILE variable in the
.env file. By default only the
local_override.yml file is enabled.
By default, the “web” docker container only “exposes” port 80. The local override file takes things one step further and maps the host port 80 to the web container port 80. This is done via an override because docker compose doesn’t support unmapping ports and the proxy_override settings need to map the reverse proxy to host port 80.
Enabling this override sets up shibboleth authentication on the apache server.
To use pre-existing shibboleth certificates, place sp-cert.pem and sp-key.pem
docker/volumes/shib-certs. This override file
also uses LetsEncrypt to get a certificate for the site using the DOMAIN
and CONTACT_EMAIL settings from the
.env file. SSL certs are stored in
docker/volumes/ssl-certs. Right now this is the only override that provides
SSL capabilities. In the future there will likely be an SSL_override file that
breaks out the LetsEncrypt functionality.
Enabling this override file sets up a reverse proxy using Traefik. This
functionality is in development and mostly untested. It currently only works
with shib_override. It also requires an already created docker network named