search

digitalfabrik / integreat-cms

Simplified content management back end for the Integreat App - a multilingual information platform for newcomers
https://digitalfabrik.github.io/integreat-cms/
Apache License 2.0
55 stars 33 forks source link
cms cms-django django e-government hacktoberfest headless-cms integration integreat multilingual newcomers python3 refugees

readme

CircleCI Pylint Coverage PyPi Release Notes License Code style: black

Integreat Django CMS

Logo Integreat - The mobile guide for newcomers. Multilingual. Offline. Open Source.

This content management system helps local integration experts to provide multilingual information for newcomers.

Development Setup

This section provides a brief overview of setting up the development environment. We support various environments: you can set up everything locally using your preferred package manager, use it as a devcontainer, or utilize the nix-flake. Please clone the repository with the following snippet before starting to set up your development environment.

git clone git@github.com:digitalfabrik/integreat-cms.git
cd integreat-cms

Choosing your setup method

From the three provided development setup options, choose yours based on personal preference and familiarity with the used tools. If you are unsure, the following might help you make a decision. Please note that these are only suggestions.

Local Setup

To configure your development environment on your system, please follow these steps carefully.

  1. Ensure that the following packages are installed alongside your preferred IDE:
    • npm version 7 or later
    • nodejs version 18 or later
    • python3 version 3.11 or later
    • python3-pip (Debian-based distributions) / python-pip (Arch-based distributions)
    • python3-venv (only on Debian-based distributions)
    • gettext for translation features
    • Either postgresql or docker to run a local database server
  2. Execute tools/install.sh to download all dependencies.
  3. Execute tools/migrate.sh to apply all database schema migrations.
  4. Optionally, run tools/loadtestdata.sh to apply a predefined set of test data.

Devcontainer

To configure your development container, please follow these steps carefully.

  1. Make sure you have Docker and VSCode (not VSCodium) installed on your machine.
  2. Open the project in VSCode.
  3. If you're opening VSCode for the first time, you'll be prompted to install the "Dev Containers" extension. Click "Install" to proceed.
  4. Open the command palette (Ctrl + Shift + P or Cmd + Shift + P on macOS) and search for "> Remote-Containers: Open Folder in Container".
  5. VSCode will open the project in a new container, install all further required tools and load the testdata.

Known Limitations

The perfect is the enemy of the good; thus, this section illuminates aspects of our evolving development setup.

Sharing git username and email

A known limitation exists where certain versions of Visual Studio Code (VSCode) may not copy the user's .gitconfig file correctly into the Devcontainer environment. In such cases, when you attempt to commit changes within the Devcontainer, you may be prompted to enter your Git username and email every time. This can be inconvenient and disrupt the workflow. However, there is a workaround for this issue. You can resolve it by appending the content of your personal .gitconfig file, located at $HOME/.gitconfig, to the end of the repository-specific .git/config file, which in this case would be integreat-cms/.git/config. By doing so, you ensure that the necessary Git configuration settings are correctly applied within the Devcontainer environment, allowing for a smoother development experience.

For more information, refer to this issue in the VSCode Remote Extension repository.

Docker permissions

The user must be in the docker group on linux, VSCode does not allow to optionally enter sudo password.

Nix Flake

To configure your development environment through the provided nix flake, follow these steps carefully.

  1. Install nix. Depending on your distribution or operating system, multiple ways might be available to do this; one recommended way is to use the install script provided by zero-to-nix.com: 
    curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
  2. Run nix develop inside your project directory. You should see nix pulling in the required dependencies for running the project.
  3. Execute tools/install.sh to download and install all project dependencies.

Please note that closing the shell in which you ran nix develop will destroy your development environment, i.e. any time you want to work on the project again, you will need to execute nix develop beforehand, and then start your code editor (code ., nvim,...) from within that same shell.

Known Limitations

On MacOS, installing libmagic separately through brew install libmagic might be required.

Run development server

Run the development server using /tools/run.sh, then open your browser and go to http://localhost:8000. The default login credentials are username: "root" and password: "root1234".

Documentation

For detailed instructions, tutorials and the source code reference have a look at our great documentation:

:notebook: https://digitalfabrik.github.io/integreat-cms/

Alternatively, you can generate it yourself using the tools/make_docs.sh script.

Project Architecture / Reference

To better understand the overall intention it might also be helpful to look at the wiki for municipalities (GER) that teaches how to use our CMS.

License

Copyright © 2018 Tür an Tür - Digitalfabrik gGmbH and individual contributors. All rights reserved.

This project is licensed under the Apache 2.0 License, see LICENSE and NOTICE.md.