This is a fork. It was created because of power structures of the upstream repo that @mariha is not compatible with.

karrot-backend

Django API server for the karrot frontend

Our issues are tracked in the karrot-frontend (fork). We plan to unite karrot-backend, karrot-frontend and related repos in near future.

Developer setup

Experimental new podman setup

This runs all the app code locally on your machine, and the services (database, redis, etc.) in containers using podman.

Prerequisites:

• python3 (I use rtx to install specific version)
• podman (docker without the daemon or root power)

# if not using rtx, create a virtualenv
python -m venv env

# install deps
./sync.py

# start it all up
./scripts/dev

Everything should be up and running now.

docker-compose setup

Includes backend, frontend, mail catcher, postgres, redis, etc..

Head over to karrot-dev/karrot-docker for further instructions.

Manual setup

You can also just run everything locally if you want.

If you want help/tips you can chat with us at:

• #karrot:matrix.org
• Karrot Team & Feedback group on Karrot itself

Configuration options

If you want to configure some options, create a .env file. Check config/options.env (base config) and/or config/dev.env (if MODE=dev) for ideas of what to put in it.

These are processed by config/options.py and then config/settings.py.

You can also create a config/local_settings.py if you want, and it'll override everything, but better to use a .env if you can.

Coding guidelines

We use various code tools, which are run when you commit using pre-commit. Check .pre-commit-config.yaml to see more there.

In short, if you commit, and it makes changes, add the changes, and commit again.

Using the API

A live dev instance of karrot is running at https://dev.karrot.world/. See https://dev.karrot.world/docs/ for API documentation. Most endpoints are only available to authenticated users. Be sure to create an account and log in to see all endpoints.

IDE

Most of karrot developers use PyCharm. We have some licenses available for the professional version. The free community edition also works well.

To get proper introspection and support from PyCharm, it's necessary to set up a virtualenv. Run this inside the backend directory:

python -m venv env
source env/bin/activate
./sync.py

Django quick introduction

The manage.py application can be used to perform administrative tasks:

• makemigrations: Create database migrations
• migrate: Apply database migrations
• shell_plus: for playing in a django python environment
• test: Run automated tests

You can launch them via docker-compose, for example:

docker-compose exec backend ./manage.py makemigrations
docker-compose exec backend ./manage.py migrate

If you spend too much time typing those long commands, consider creating your own bash aliases.

Speed up testing

When running tests, use ./scripts/test, which will configure the test runner to use config/test_settings.py. It is much faster.

Parallel testing: Running the tests in parallel process can increase testing speed significantly:

./scripts/test --parallel auto

Run tests selectively: If you want to run only a single test, let's say TestGroupManager in karrot/groups/tests/test_model.py, you can do so by using dot-syntax:

./scripts/test karrot.groups.tests.test_model.TestGroupManager

Email template viewer

When editing emails it's useful to be able to see how they will be rendered.

Assuming the server is running you can visit visit localhost:8000/_templates.

To compile the .mjml templates to .html.jinja2 files you can run:

cd mjml
yarn
./convert

Note: you should never edit .html.jinja2 files directly.

Enjoy! ... oh and be sure to visit https://mjml.io/documentation/#components to find some nice components to use.