weblate / gcampus Goto Github PK

GewässerCampus (gcampus) is part of an educational project on Limnology aiming to provide students the possibility to analyse, publish and discuss results of self-conducted measurements of water-quality in rivers and lakes. It is developed by desklab in cooperation with the TU Kaiserslautern and funded by the DBU. See gewaessercampus.de for more information.

This repository (desklab/gcampus) contains the source code running behind the GewässerCampus-web-application. The landingpage is developed in desklab/gcampus-landingpage.

Contributions in the form of reporting issues or submitting pull requests are welcome! Please use the available tools as described here to ensure your changes of the code could be merged. As this project addresses primarily a special group of users (students/teachers) and must retain compatibility to the software and devices developed by desklab (some of which may not be public yet), there may be some additional requirements, which can not be covered by automated tests. Therefore you should not hesitate to contact us via [email protected] or by opening an issue, if you are planning to contribute to this project, such that we could discuss the best way to go forward. Submitted code changes are understood to be under the same license that covers the project.

There are mainly two aspects to developing gcampus. There is

1. the django python backend and
2. static files like JavaScript or stylesheets.

The basic requirements for running gcampus are:

• Python 3.8 or newer
• PostgreSQL with PostGIS (serves as a database)
• Redis (used for Celery tasks)
• libgdal (required for GeoDjango)
• Node.js and npm (for static files)

As we use the GeoDjango extension for Django, a few extra things are needed. Geospatial data can not be stored in any old SQLite database but requires e.g. PostGIS. Additionally, GDAL is required. 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 Miniconda is recommended for a small footprint.

Create a new Python environment:

conda create -n gcampus python=3

Later, this environment can be activated with conda activate gcampus. It should be indicated by (gcampus) at the beginning of your terminal prompt. Note that PyCharm also integrates nicely with conda.

Python packages can be easily installed using pip:

pip install -r requirements.txt
# Optional (e.g. for black)
pip install -r requirements-dev.txt

To install GDAL, run the following command:

conda install -c conda-forge libgdal

WeasyPrint is used to generate PDF documents e.g. for the token list. Install instructions can be found in WeasyPrint's documentation.

Make sure you have Node.js installed. We use webpack to build stylesheets and bundle JavaScript.

npm install -g webpack-cli
npm install

npm run dev

A docker-compose.yml file is provided to easily get a PostGIS and Redis instance up and running. As we are using GeoDjango, PostGIS is required. Redis is used for the Celery task queue.

docker volume create gcampus-data

docker-compose up -d

You can check the current status using docker-compose ps. The PostgreSQL with PostGIS should be up and running at port 5432.

Before you can run the development server, make sure all migrations have been applied by running

python manage.py migrate

Always make sure to apply migrations and check after pulling from git if there are new migrations.

You can load a predefined fixture called fixture.json that already includes some dummy fields and an admin user with the username admin and password admin:

python manage.py loaddata fixture.json

Finally, you can run the development server:

python manage.py runserver

Celery is used to process tasks such as document generation. You can run a worker using the celery command:

celery --app=gcampus.tasks worker -l INFO

Change -l INFO to an appropriate log level of your liking.

Testing can be done using django's built in test command:

python manage.py test

Support for coverage.py is provided through the configuration in the pyproject.toml file. You can run the tests and get the results using the following commands:

coverage run
# Preview coverage results:
coverage report

A Dockerfile is provided to easily build gcampus for production usage. Note that this Dockerfile only runs a gunicorn server to serve the django backend. Static files need to be served separately. In production, this is done by using a S3 compatible object storage.

GewässerCampus (gcampus) is licensed under the Affero General Public License (AGPL) version 3. Its terms and conditions can be found in the LICENSE file.