kompass/README.md

kompass

Kompass is an administration platform designed for local sections of the Young German Alpine Club. It provides tools to contact and (automatically) manage members, groups, material, excursions and statements.

For more details on the features, see the (German) documentation.

Contributing

Any form of contribution is appreciated. If you found a bug or have a feature request, please file an issue. If you want to help with the documentation or want to contribute code, please open a pull request.

The following is a short description of the development setup and an explanation of the various branches.

Development setup

The project is run with docker and all related files are in the docker/ subfolder. Besides the actual Kompass application, a database (postgresql) and a broker (redis) are setup and run in the docker container. No external services are needed for running the development container.

Initial installation

A working docker setup (with docker compose support) is required. For installation instructions see the docker manual.

1. Clone the repository and change into the directory of the repository.

2. Fetch submodules

   git submodule update --init
   

3. Prepare development environment: to allow automatic rebuilding upon changes in the source, the owner of the /app/jdav_web directory in the docker container must agree with your user. For this, make sure that the output of echo UID and echo UID is not empty. Then run

   export GID=${GID}
   export UID=${UID}
   

4. Start docker

   cd docker/development
   docker compose up
   

   This runs the docker in your current shell, which is useful to see any log output. If you want to run the development server in the background instead, use docker compose up -d.

   During the initial run, the container is built and all dependencies are installed which can take a few minutes. After successful installation, the Kompass initialization runs, which in particular sets up all tables in the database.

5. Setup admin user: in a separate shell, while the docker container is running, run

   cd docker/development
   docker compose exec master bash -c "cd jdav_web && python3 manage.py createsuperuser"
   

   This creates an admin user for the administration interface.

Development

If the initial installation was successful, you can start developing. Changes to files cause an automatic reload of the development server. If you need to generate and perform database migrations or generate locale files, use

cd docker/development
docker compose exec master bash
cd jdav_web

This starts a shell in the container, where you can execute any django maintenance commands via python3 manage.py <command>. For more information, see the django documentation.

Testing

To run the tests, you can use the docker setup under docker/test.

Known Issues

• If the UID and GID variables are not setup properly, you will encounter the following error message after running docker compose up.

  => ERROR [master 6/7] RUN groupadd -g  fritze && useradd -g  -u  -m -d /app fritze                                                                                                                0.2s
  ------
  > [master 6/7] RUN groupadd -g  fritze && useradd -g  -u  -m -d /app fritze:
  0.141 groupadd: invalid group ID 'fritze'
  ------
  failed to solve: process "/bin/sh -c groupadd -g $GID $USER && useradd -g $GID -u $UID -m -d /app $USER" did not complete successfully: exit code: 3
  

  In this case repeat step 3 above.

Organization and branches

The stable development happens on the main branch for which only maintainers have write access. Any pull request should hence be targeted at main. Regularly, the production instances are updated to the latest main version, in particular these are considered to be stable.

If you have standard write access to the repository, feel free to create new branches. To make organization easier, please indicate your username in the branch name.

The testing branch is deployed on the development instances. No development should happen there, this branch is regularly reset to the main branch.