Django API server for the karrot frontend

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

CircleCI codecov

Developer setup

The recommended way to getting your developer environment setup is docker-compose - includes backend, frontend, mail catcher, postgres, redis, etc..

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

If you can't or don't want to use docker-compose, look into SETUP.md for other ways.

Coding guidelines

We follow PEP8 with the same rules as the Django project. As always, the coding style may not apply at some parts. You can execute flake8 in the repository root to check your code.

Code will only be accepted into master if it passes the PEP8 test.

Using the API

A live instance of karrot is running at https://karrot.world/. See https://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.


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:

virtualenv env
source ./env/bin/activate
pip install pip-tools

Django quick introduction

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

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

Parallel testing: Running the tests in parallel process can increase testing speed significantly. To execute the whole test suite on a CPU with 4 kernels, you may want to use:

docker-compose exec backend ./manage.py test --parallel 4

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:

docker-compose exec backend ./manage.py test karrot.groups.tests.test_model.TestGroupManager

Hint: To speed up test development, pprint might be useful to you.

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

If you want to watch for changes, and support hot reloading then run:

./convert --watch

(refresh your browser after starting the server as the websocket is not reconnecting)

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.