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 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.
  • Go to the directory which contains the code on your computer, you'll be working from there from here on out.
  • 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
  • In .env, change DEBUG to true
  • Optionally, you can use a service like ngrok to set up a domain name, and set the DOMAIN variable in your .env file to the domain name generated by ngrok.

  • Unless you want to set up your local machine to support https during development, you may want to set USE_HTTPS=false. If you try to register your admin account and see a message that CSRF verification failed, you should set this option.

  • Set up nginx for development by copying the developer nginx configuration file (nginx/development) into a new file named nginx/default.conf:

cp nginx/development nginx/default.conf
  • Start the application. 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
  • Once the build is complete, you can access the instance at http://localhost:1333 and create an admin user.

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.