Karrot Docs

Appearance

Without docker ​

Who needs all that docker nonsense! Let's just run it on the machine...

Prerequisites ​

You'll need:

  • a computer to run it on - I'll be assuming you have a Linux machine
  • python, pip, and a way to create virtualenvs installed - we suggest python v3.12
  • nodejs installed - for compiling email templates
  • PostgreSQL and Redis set up and running - setting these up is outside the scope of this guide

When running in production you'll also need:

  • a webserver that can be configured to serve static assets and proxy requests, e.g. nginx
  • a way to run/monitor processes, e.g. systemd

Choose which version of Karrot you want to run ​

Selected version

Choose a version to run, using latest will run the pre-released code, which corresponds to the main branch of frontend and backend code. This is not recommended for production use.

For production use run the most recently released version.

To run a specific version:

  • find a release over at Karrot Releases
  • checkout any repo you clone at that release, e.g. git checkout
  • if you download static assets, replace latest with the version number

Setup the backend ​

shell
git clone https://codeberg.org/karrot/karrot-backend.git
cd karrot-backend
git checkout main
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python manage.py collectstatic
python manage.py check

Compile the email templates ​

The email templates are written in mjml which need compiling to jinja2 templates for Django.

shell
cd mjml
yarn
./convert

Configuration ​

You can set environment variables, or put them in a .env file in the project root.

See the Configuration Settings page for what to set, they mostly have sensible/obvious defaults for trying it out.

If you don't have an SMTP server to hand to configure it with, you can get it to print emails to the console with:

shell
EMAIL_BACKEND=console

Run the migrations ​

Now, you should be connected to the database, you can run the database migrations.

shell
python -m karrot.cli migrate

Try it out! ​

If that all worked, it should be ready to see if the server runs:

shell
python -m karrot.cli server

By default it should now be running on localhost:8000. You can try visiting a few URLs to see if it's working:

You also need to run a worker that will handle background tasks:

shell
python -m karrot.cli worker

Setup the frontend ​

The frontend consists of a directory of static files.

You can use our prebuilt files (latest) to save building the frontend project yourself.

shell
# if you're in still in karrot-backend dir, you might want to "cd .." first
mkdir karrot-frontend
curl https://codeberg.org/api/packages/karrot/generic/karrot-frontend/latest/karrot-frontend.tar.gz | tar xzvf - -C karrot-frontend
If you want to build it yourself...
shell
git clone https://codeberg.org/karrot/karrot-frontend.git
cd karrot-frontend
git checkout main
yarn
yarn build
# The built files will be in dist/pwa

For small setups, or for trying it out, you can get the backend to serve the assets directly by adding this configuration:

shell
# This is needed as it defaults to assuming the frontend is served separately at localhost:8080
BASE_URL=http://localhost:8000
# Make sure this dir points to the directory that has index.html in it
FRONTEND_DIR=/your/path/to/karrot-frontend

How does it serve the files? Is it fast enough?

It does the best it can for python serving files:

  • static assets are not served through Django, but handled at the lowest level asgi layer via Starlette Static Files with Uvicorn
  • user uploaded files are send via a Django FileResponse which streams them
  • cache headers are set for maximum caching

In production you should run a separate webserver

Whilst we made it serve them as fast as python can manage, in production you'd still want a proper webserver like nginx.

The webserver will serve the static assets and proxy the API calls to the backend.

A webserver will also handle serving over https:// which you'd also want.

You can take inspiration from our nginx.conf.template which we use for our frontend docker image.

Create some sample data (optional) ​

If you want some sample data to play around with, you can run:

shell
python -m karrot.cli manage create_sample_data

Then log in as foo@foo.com / foofoo (or any other user account with password 123)

Putting it all together ​

So, by now you should have:

  • PostgreSQL running
  • Redis running
  • python -m karrot.cli server running
  • python -m karrot.cli worker running
  • the frontend assets in a directory being served by Karrot