Merge pull request #223 from hughrun/required-envs

Minimum required env values and other fixes

Author: hughrun

content/contributing/install-dev.md

@@ -14,7 +14,8 @@ These instructions assume you are developing BookWyrm using Docker. You'll need
 
 1. Get a copy of [the BookWyrm codebase from GitHub](https://github.com/bookwyrm-social/bookwyrm). You can [create a fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) of the repository, and then [use `git clone` to download the code](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository-from-github/cloning-a-repository) 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. 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:
+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:
 ``` { .sh }
 cp .env.example .env
 ```
@@ -28,11 +29,13 @@ In `.env`:
 6. change `NGINX_SETUP` to `reverse_proxy` (this prevents BookWyrm trying to set up https certificates on your development machine)
 7. 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.
 
-If you try to register your admin account and see a message that `CSRF verification failed`, you should check these settings, as you may have set your domain or port incorrectly.
+Check that you have [all the required settings configured](/environment.html#required-environment-settings) 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 values](/environment.html#email-configuration) in the "Email config" section. You do not need to change anything for [the separate `EMAIL` setting](/environment.html#email).
+If you want to test sending emails, you will need to [set up appropriate real values](/environment.html#email-configuration) in the "Email config" section. You do not need to change anything for [the separate `EMAIL` setting](/environment.html#email).
 
 ### Build and run
 

content/index.md

@@ -6,7 +6,7 @@ Date: 2021-04-13
 BookWyrm is a social network for tracking your reading, talking about books, writing reviews, and discovering what to read next. Federation allows BookWyrm users to join small, trusted communities that can connect with one another, and with other ActivityPub services like Mastodon and Pleroma.
 
 ## Features
-Since the project is still in its early stages, the features are growing every day, and there is plenty of room for suggestions and ideas. Open an [issue](https://github.com/bookwyrm-social/bookwyrm/issues) to get the conversation going!
+The features are growing every month, and there is plenty of room for suggestions and ideas. Open an [issue](https://github.com/bookwyrm-social/bookwyrm/issues) to get the conversation going, or [find a good first issue](https://github.com/bookwyrm-social/bookwyrm/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) to make your first contribution!
 
 - Posting about books
     - Compose reviews, with or without ratings, which are aggregated in the book page
@@ -19,9 +19,10 @@ Since the project is still in its early stages, the features are growing every d
 - Track reading activity
     - Shelve books on default "to-read," "currently reading," "stopped reading," and "read" shelves
     - Create custom shelves
-    - Store started reading/finished reading dates, as well as progress updates along the way
+    - Store started/stopped/finished reading dates, as well as progress updates along the way
     - Update followers about reading activity (optionally, and with granular privacy controls)
     - Create lists of books which can be open to submissions from anyone, curated, or only edited by the creator
+    - Create groups with other BookWyrm users and collaborate with group-owned lists
 - Federation with ActivityPub
     - Broadcast and receive user statuses and activity
     - Share book data between instances to create a networked database of metadata

content/reference/environment.md

@@ -4,11 +4,62 @@ Date: 2025-04-28
 Order: 1
 ---
 
-BookWyrm requires certain environment (`ENV`) variables in order to run correctly. These are set from a file named `.env` in the directory you run BookWyrm from. You will find most of these variabled described in the `.env.example` file in the main code repository. You should copy this as the basis of your `.env` file.
+BookWyrm servers require certain environment (`ENV`) variables in order to run correctly. These are set from a file named `.env` in the directory you run BookWyrm from. You will find most of these variabled described in the `.env.example` file in the main code repository. You should copy this as the basis of your `.env` file.
 
 BookWyrm **instance administrators** should carefully check version release notes for any changes or additions to environment variables.
 
-BookWyrm **developers** should prefer to use `site.settings` for configuration rather than `ENV` values if possible.
+Wherever possible BookWyrm **developers** should prefer to use `site.settings` when creating new configuration values rather than `ENV` values.
+
+## Required settings
+
+The `env.example` file includes default values for core settings. These are designed to be safe defaults for production, apart from the default passwords. Docker users can run `./bw-dev create_secrets` to create safe and unique secrets for:
+
+* `SECRET_KEY`
+* `POSTGRES_PASSWORD`
+* `REDIS_ACTIVITY_PASSWORD`
+* `REDIS_BROKER_PASSWORD`
+* `FLOWER_PASSWORD`
+
+You _must_ assign an appropriate value to all of these settings, in your `.env` file:
+
+* `SECRET_KEY`
+* `DOMAIN`
+* Flower:
+    * `FLOWER_USER`
+    * `FLOWER_PASSWORD`
+    * `FLOWER_PORT`
+* Email (in development these may be blank strings but still need to be set):
+    * `EMAIL_HOST`
+    * `EMAIL_PORT`
+    * `EMAIL_HOST_USER`
+    * `EMAIL_HOST_PASSWORD`
+    * `EMAIL_USE_TLS`
+    * `EMAIL_USE_SSL`
+    * `EMAIL_SENDER_NAME`
+* Postgres:
+    * `POSTGRES_USER`
+    * `POSTGRES_DB`
+    * `POSTGRES_HOST`
+    * `POSTGRES_PASSWORD`
+* Redis:
+    * `REDIS_BROKER_HOST`
+    * `REDIS_BROKER_PORT`
+    * `REDIS_ACTIVITY_HOST`
+    * `REDIS_ACTIVITY_PORT`
+    * `REDIS_ACTIVITY_PASSWORD`
+    * `REDIS_BROKER_PASSWORD`
+
+When running BookWyrm in **development**:
+
+* `NGINX_SETUP` **must** be set to `reverse_proxy`
+* `DEBUG` _should_ be set to `true`
+* `DOMAIN` may be `localhost`
+
+When running BookWyrm in **production**:
+
+* `DEBUG` **must** be set to `false`
+* `DOMAIN` **must not** be `localhost`
+* Email settings **must** be real and use a bulk email provider such as mailgun
 
 ## Django settings
 

content/running_bookwyrm/install-prod.md

@@ -30,13 +30,14 @@ Instructions for running BookWyrm in production:
     - `FLOWER_USER` | Your own username for accessing Flower queue monitor
     - `EMAIL_HOST_USER` | The "from" address that your app will use when sending email
     - `EMAIL_HOST_PASSWORD` | The password provided by your email service
-- Initialize secrets by running `bw-dev create_secrets` or manually update following in `.env`:
+- Initialize secrets by running `./bw-dev create_secrets` or manually update following in `.env`:
     - `SECRET_KEY` | A difficult to guess, secret string of characters
     - `POSTGRES_PASSWORD` | Set a secure password for the database
     - `REDIS_ACTIVITY_PASSWORD` | Set a secure password for Redis Activity subsystem
     - `REDIS_BROKER_PASSWORD` | Set a secure password for Redis queue broker subsystem
     - `FLOWER_PASSWORD` | Your own secure password for accessing Flower queue monitor
     - If you are running another web-server on your host machine, you will need to follow the [reverse-proxy instructions](/reverse-proxy.html)
+- Check that you have [all the required settings configured](/environment.html#required-environment-settings) before proceeding further
 - Setup ssl certificate via letsencrypt by running `./bw-dev init_ssl`
 - Initialize the database by running `./bw-dev migrate`
 - Run the application with