This guide is intended as a help for setting up a development
gcampus. While we try to be as lean as possible when
it comes to outside dependencies, there is still a significant amount
of additional software that is required for the web application. All
this requirements serve a specific purpose as listed below:
Document factory: WeasyPrint (used to create downloadable PDFs)
Django, GeoDjango, Celery and WeasyPrint#
Recommended Setup with
As we use Django’s GeoDjango module, a few extra steps are
required to get started.
Geospatial is best stored in PostgreSQL with the PostGIS extension.
Additionally, GeoDjango requires the GDAL library. The easiest
and recommended solution for all this is to use
conda as a Python
environment. You can install any
conda distribution you like, but
recommended for a small footprint.
To set up the environment, a
environment.yml file is provided in the
root of the repository:
conda env create -f environment.yml
This should create a new environment called
gcampus which can be
conda activate gcampus. The
tells conda to install all the required packages such as:
All other Python dependencies located in the
requirements.txt will be
installed automatically using
pip. This is also where the Celery
dependency is found.
The Do-It-Yourself Setup Variant#
conda works great for most - especially on macOS on which it is
not trivial to install GDAL - other users may choose a different route
to install dependencies and manage Python. For this case, we provide
an unordered list of resources that should help you get stated:
Redis can be installed using a package manager such as
macOS or your distro’s package manager if you are on GNU/Linux.
This method is recommended as it has a rather small footprint.
Alternatively, you can use Docker and the provided
file to run Redis with the following command:
docker-compose up redis -d
PostgreSQL with PostGIS#
Recommended for macOS users that do not want to use Docker. Install
postgis with conda:
conda install postgis -c conda-forge
Choose a directory in which you want to put the database files. Replace
<database dir> in the following commands with your directory:
pg_ctl init -D database pg_ctl start -D database --log=database.log createuser --superuser --encrypted --pwprompt gcampus createdb --owner=gcampus gcampus
When asked for the password for the user
This is the default password used in the development environment.
docker-compose.yml file contains everything needed to get
a working PostgreSQL server with PostGIS up and running:
docker-compose up postgis -d
Node.js and npm#
Refer to the documentation and download page of Node.js for instructions. We recommend the latest LTS release.
Once you installed Node.js and npm you can install the required
dependencies located in
package.json using one of the following commands:
npm ci # installs the packages as they are in package-lock.json npm install # installs packages as stated in package.json
You will need to set the environment variable
with a valid Mapbox access token for some things to work properly.
Prepare database and load example data (to get a clean database after a reset refer to Mockup):
python manage.py migrate python manage.py loaddata production.json python manage.py loaddata fixture.json
A user with credentials
admin will be created from the
fixture. Note that the fixture does not include the default permissions.
To apply these permissions to all token users, run the following
python manage.py defaultpermissions
Build static files using webpack:
npm run dev # or alternatively npm run build
Run a Celery worker:
celery --app=gcampus.tasks worker -l INFO