This is the documentation for the current development code. Choose a version from the menu to see documentation for released versions since v0.7.5.

Developer Environment

Prerequisites

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

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

Configure your environment settings

In .env:

  1. change DEBUG to true
  2. 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). Otherwise, set DOMAIN to localhost
  3. change NGINX_SETUP to reverse_proxy (this prevents BookWyrm trying to set up https certificates on your development machine)
  4. If you need to use a particular port (e.g. if you are tunneling via ngrok), uncomment PORT and set it (e.g. PORT=1333). If using localhost this is optional.

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.

Build and run

  1. In the command line, run:
./bw-dev build            # Build the docker images
./bw-dev setup            # Initialize the database and run migrations. Note the ADMIN key at the end of this output. You'll need it to register the first admin user.
./bw-dev up               # Start the docker containers
  1. Once the build is complete, you can access the instance at http://localhost, your ngrok domain, or http://localhost:{PORT}, depending on you domain and port configuration.
  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 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 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.