Developer Environment

Prerequisites

These instructions assume you are developing BookWyrm using Docker. You'll need to install Docker and docker-compose to get started.

If you are contributing to BookWyrm in a dockerless development environment we would love for you to help us update this guide to include instructions for setting up a dockerless development environment.

Setting up the developer environment

Get the code

1. Get a copy of the BookWyrm codebase from GitHub. You can create a fork of the repository, and then use git clone to download the code to your computer.
2. Go to the directory which contains the code on your computer, you'll be working from there from here on out.
3. Development occurs on the main branch, so ensure that is the branch you have checked out: git checkout main
4. Set up your development environment variables file by copying the example environment file (.env.example) into a new file named .env. In the command line, you can do this with:

cp .env.example .env

Build and run

1. In the command line, run:

./bw-dev create_secrets       # Create the secrets file with random values. You only need to do this once.
./bw-dev dev up --build       # Build and start development stack
./bw-dev rundev python manage.py admin_code       # Shows the admin-code for initial setup. You only need to do this once.

1. Once the build is complete, you can access the instance at http://localhost:1333.
2. You can now enter your admin key and create an admin user. From here everything is the same as described in "Running BookWyrm".

If you're curious: the ./bw-dev command is a simple shell script runs various other tools: above, you could skip it and run docker-compose build or docker-compose up directly if you like. ./bw-dev just collects them into one common place for convenience. Run it without arguments to get a list of available commands, read the documentation page for it, or open it up and look around to see exactly what each command is doing!

Editing or creating Models

If you change or create a model, you will probably change the database structure. For these changes to have effect you will need to run Django's makemigrations command to create a new Django migrations file, and then migrate it:

./bw-dev makemigrations
./bw-dev rundev python manage.py migrate

Editing static files

Any time you edit the CSS or JavaScript, you will need to run Django's collectstatic command again in order for your changes to have effect:

./bw-dev rundev python manage.py collectstatic

If you have installed yarn, you can run yarn watch:static to automatically run the previous script every time a change occurs in bookwyrm/static directory.

Run code-linters and formatters

Before submitting patch, you should check ruff and other formatting tools. For those to work nicely, you should make sure you have development web-container and dev-tools build.

./bw-dev dev build # This is needed only once, if you haven't run dev stack previously
./bw-dev dev build dev-tools # This is needed only once and if you change pyproject.toml or Dockerfile

After those commands, you can run formatters and pytest and mypy with bw-dev command:

./bw-dev formatters
./bw-dev mypy
./bw-dev pytest

Run development code behind ngrok or other tunneling/proxy service

In .env.dev:

1. If you use a tunneling/proxy service like ngrok, set DOMAIN to to the domain name you are using (e.g. abcd-1234.ngrok-free.app).
2. If you need to use a particular port other than 1333, change PORT to wanted port (e.g. PORT=1333).

Check that you have all the required settings configured before proceeding.

If you try to register your admin account and see a message that CSRF verification failed you may have set your domain or port incorrectly.

Email (optional)

If you want to test sending emails, you will need to set up appropriate real values in the "Email config" section. You do not need to change anything for the separate EMAIL setting. These settings are in .env -file