|
|
|
|
@ -2,29 +2,105 @@
|
|
|
|
|
|
|
|
|
|
[](https://jenkins.merten.dev/job/gitea/job/kompass/job/main/)
|
|
|
|
|
|
|
|
|
|
This repository has the purpose to develop a webapplication that can be used by
|
|
|
|
|
JDAV to send newsletters, manage user lists and keep material lists up to date.
|
|
|
|
|
As this repository is also meant to be a base for exchange during development, feel free
|
|
|
|
|
to contribute ideas in form of edits to this README, issues, landmarks, projects, wiki entries, ...
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
# Docker
|
|
|
|
|
For more details on the features, see the (German) [documentation](https://jdav-hd.de/static/docs/index.html).
|
|
|
|
|
|
|
|
|
|
In the `docker` subfolder, there are `docker-compose.yaml`s for development and production use. For the development
|
|
|
|
|
version, no further setup is needed.
|
|
|
|
|
# Contributing
|
|
|
|
|
|
|
|
|
|
# Production
|
|
|
|
|
Any form of contribution is appreciated. If you found a bug or have a feature request, please file an
|
|
|
|
|
[issue](https://git.jdav-hd.merten.dev/digitales/kompass/issues). If you want to help with the documentation or
|
|
|
|
|
want to contribute code, please open a [pull request](https://git.jdav-hd.merten.dev/digitales/kompass/pulls).
|
|
|
|
|
|
|
|
|
|
In production, the docker setup needs an external database. The exact access credentials are configured in the respective
|
|
|
|
|
docker.env files.
|
|
|
|
|
The following is a short description of the development setup and an explanation of the various
|
|
|
|
|
branches.
|
|
|
|
|
|
|
|
|
|
# Useful stuff
|
|
|
|
|
## Development setup
|
|
|
|
|
|
|
|
|
|
## Reset database for certain app
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
The following can be useful in case that automatic migrations throw errors.
|
|
|
|
|
### Initial installation
|
|
|
|
|
|
|
|
|
|
1. delete everything in the migrations folder except for __init__.py.
|
|
|
|
|
2. drop into my MySQL console and do: DELETE FROM django_migrations WHERE app='my_app'
|
|
|
|
|
3. while at the MySQL console, drop all of the tables associated with my_app.
|
|
|
|
|
4. re-run ./manage.py makemigrations my_app - this generates a 0001_initial.py file in my migrations folder.
|
|
|
|
|
5. run ./manage migrate my_app - I expect this command to re-build all my tables, but instead it says: "No migrations to apply."
|
|
|
|
|
A working `docker` setup (with `docker compose` support) is required. For installation instructions see the
|
|
|
|
|
[docker manual](https://docs.docker.com/engine/install/).
|
|
|
|
|
|
|
|
|
|
1. Clone the repository and change into the directory of the repository.
|
|
|
|
|
|
|
|
|
|
2. Fetch submodules
|
|
|
|
|
```bash
|
|
|
|
|
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
|
|
|
|
|
```bash
|
|
|
|
|
export GID=${GID}
|
|
|
|
|
export UID=${UID}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
4. Start docker
|
|
|
|
|
```bash
|
|
|
|
|
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
|
|
|
|
|
```bash
|
|
|
|
|
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](https://docs.djangoproject.com/en/4.0/ref/django-admin).
|
|
|
|
|
|
|
|
|
|
### 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`.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
=> 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.
|
|
|
|
|
|
