Django API server for the karrot frontend

Our issues are tracked on our community board, and also on karrot-frontend issues.

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

• python
  • Karrot is written in python
  • optionally you can use mise to install a specific version, run mise install
  • otherwise get a version 3 of python
  • if possible use the same version as listed at the top of the Dockerfile
• nodejs
  • this is used for email templates as we use mjml.io
  • install it via your package manager or from nodejs.org
  • if you are using mise, mise install will have already installed it previously
• yarn (classic)
  • used to install nodejs dependencies
  • install it via your package manager or with npm install --global yarn
• a container runtime
  • used to run the services (postgresql, redis, etc.)
  • podman is the recommended option
    • install podman via package manager or from podman.io
  • docker is just fine too
    • install docker via package manager or from docs.docker.com/get-docker
  • nerdctl is for advanced users who know what they're doing
    • install nerdctl via package manager or see github.com/containerd/nerdctl
  • if you don't like the autodetected choice, you can set RUNTIME=<runtime>" in .env
    • e.g. RUNTIME=nerdctl

# create a virtualenv
python -m venv .venv

# if not using mise, you'll need to activate the virtualenv
source .venv/bin/activate

# install deps
./sync.py

# start it all up
./scripts/dev

It might take some time on first run, as it has to download some container images.

Once it's ready you should a line something like:

12:37:11 web.1     | Listening on TCP address 127.0.0.1:8000

Everything should be up and running now! Visiting http://localhost:8000 should show you "not found".

More interesting places to visit are:

• http://localhost:8000/docs/ - API documentation
• http://localhost:8000/api/bootstrap/ - a request that will show you some json
• http://localhost:8000/_templates - email template previews
• http://localhost:8081/ - pgweb database UI
• http://localhost:1080/ - maildev mail catcher UI

If you want a Karrot frontend, you have two options:

1. setup karrot-frontend and set BACKEND=http://127.0.0.1:8000 in .env
2. download and unpack the .tar.gz archive from a recent release and configure FRONTEND_DIR to point to the folder

You can create some interesting usable data by running:

./manage.py create_sample_data

After that you can login as foo@foo.com / foofoo

Be sure to checkout the Karrot Developer Documentation too.

You can also just run everything locally if you want:

• run postgresql
• run redis
• create config/local_settings.py and configure it to point to those
  • you can reference config/local_settings.py.example to see what to set

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

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

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.

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.

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.

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

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 like this:

./manage.py makemigrations
./manage.py migrate
./manage.py shell_plus
./manage.py test

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

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

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

When running ./scripts/dev the templates will automatically be compiled for you.

If you need to run the conversion manually though, 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.