This project aims to develop a content management system tailored to the needs of municipalities to provide multilingual local information. Its goal is to be easy to use and easy to maintain over a long time. This project uses Python3 and Django 2.2 and is supposed to run on Ubuntu 18.04.
Following packages are required for running the project (Install them with your package manager):
- git
- npm
- python3.7
- python3-pip
- pipenv for python3 (If no recent version is packaged for your distro, use
pip3 install pipenv --user
) - python3.7-dev (only on Ubuntu)
- postgresql OR docker
- GNU gettext tools (to make use of the internationalization feature)
git clone git@github.com:Integreat/cms-django.git
cd cms-django
./dev-tools/install.sh # install venv and integreat-cms
./dev-tools/run.sh # start database and integreat-cms
- Go to your browser and open the URL
http://localhost:8000
- Default user is "root" with password "root1234".
- If you not use docker as database host you may need to load sample data
First of all, clone the project:
git clone git@github.com/digitalfabrik/coldaid-backend.git
cd cms-django
Install a python virtual environment and setup integreat-cms in this venv:
./dev-tools/install.sh
If you want to use the Django command line instructions with integreat-cms
(instead of our dev-tools), you have to activate it:
pipenv shell
Otherwise python dependency modules inside the venv can not be identified.
This dev tool is a shortcut for all translation tasks:
./dev-tools/translate.sh
If you run into merge/rebase conflicts inside the translation file, use:
./dev-tools/resolve_translation_conflicts.sh
Alternatively, you can manage the translations manually. After you changed translated texts in the code, rebuild the .mo file with the following command:
integreat-cms makemessages -l de
To make use of the translations in the backend, compile the django.po file as follows:
integreat-cms compilemessages
If you are using a virtual python environment, be sure to use the ´--exclude´ parameter or execute this command in the backend or cms directory, otherwise all the translation files in your venv will be compiled, too.
You can run Postgres either in a Docker container or on your local server.
Run Postgres in our provided Docker container and start the integreat-cms
local server subsequently:
./dev-tools/run.sh
On the first run, this will also migrate the database and populate it with initial test data.
Alternatively,
- Install Postgres on your machine (Tutorial for Ubuntu 18.04)
- Adjust database credentials to the one provided by your local environment in
src/backend/settings.py
While the database is running, migrate it:
./dev-tools/migrate.sh
To import initial test data into the database, execute:
./dev-tools/loadtestdata.sh
- If you didn't use the
dev-tools/run.sh
-script in step 2.1, fire up the CMS (If port 8000 is already in use, you might use another one):
integreat-cms runserver localhost:8000
- Go to your browser and open the URL
http://localhost:8000
- Default user is "root" with password "root1234".
You may need to activate the virtual environment explicitly via pipenv shell
.
Run tests: ./dev-tools/test.sh
Run tests with code coverage report generation: ./dev-tools/test_cov.sh
To make sure your code matches the repository's quality standards, run pylint as follows:
./dev-tools/pylint.sh
Required syntax of docstrings (more information here):
"""
[Summary]
:param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]
:type [ParamName]: [ParamType](, optional)
...
:raises [ErrorType]: [ErrorDescription]
...
:return: [ReturnDescription]
:rtype: [ReturnType]
"""
If you added new dependencies to setup.py
or want to upgrade the versions of installed pip & npm dependencies, execute
./dev-tools/update_dependencies.sh
to make sure the dependency lock files are updated.
If you change models, functions or docstrings, make sure to update the corresponding developer documentation:
./dev-tools/generate_documentation.sh
This scans the source code for changed definitions and docstrings, generates intermediate .rst files and compiles them to the html documentation in /docs.
- Keep in mind that we are using Python 3.7, so use
python3
(Ubuntu:python3.7
, Arch Linux:python37
) andpip3
with any command - Access the Postgres database running in Docker container:
docker exec -it integreat_django_postgres psql -U integreat
- To ensure that you do not accidentally push your changes in
settings.py
, you can ignore the file locally viagit update-index --assume-unchanged ./backend/backend/settings.py
- Delete the database to start over again:
./dev-tools/prune_database.sh
- Create root superuser:
./dev-tools/create_superuser.sh
As the project is still in an early stage with a lot of changes to the database structure from different contributors, it can come in handy to reset the project completely. To do so, follow the this steps:
- Stop Django by pressing STRG+C
- Run
./dev-tools/prune_database.sh
(If some of the files/directories are not accessible, delete them manually withsudo rm -rf DIRECTORY/FILE
After this steps, the project should be reset completely. Follow the install instructions to keep it up running again.
Packaging for Debian can be done with setuptools.
$ pip3 install stdeb
$ python3 setup.py --command-packages=stdeb.command bdist_deb
The project requires the package python3-django-widget-tweaks which has to be built manually:
$ git clone git@github.com:jazzband/django-widget-tweaks.git
$ cd django-widget-tweaks
$ pip3 install stdeb
$ python3 setup.py --command-packages=stdeb.command bdist_deb
Then install both packages with gdebi:
# apt install gdebi postgresql
# gdebi django-widget-tweaks/deb_dist/python3-django-widget-tweaks_1.4.3-1_all.deb
# gebi cms-django/deb_dist/python3-integreat-cms_0.0.13-1_all.deb
In the end, create a PostgreSQL user and database and adjust the /usr/lib/python3/dist-packages/backend/settings.py
.