diff --git a/README.md b/README.md
index 81df26c..dc994bb 100644
--- a/README.md
+++ b/README.md
@@ -9,10 +9,19 @@ Please read the [full terms](./LICENSE.md) for proper wording.
 
 # installing & first time setup
 ## docker (production)
-create `config/secrets.prod.env` according to `config/secrets.prod.env.example`
+1. clone the repo
+2. create `config/secrets.prod.env` according to `config/secrets.prod.env.example`
+3. create `config/pyrom_config.toml` according to `config/pyrom_config.toml.example` and modify as needed
+4. make sure the `data/` folder is writable by the app:
 
 ```bash
-$ docker compose up
+$ chmod -R 777 data/
+```
+
+5. bring up the container:
+
+```bash
+$ docker compose up --build
 ```
 
 - opens port 8080
@@ -20,10 +29,10 @@ $ docker compose up
 
 make sure to run it in an interactive session the first time, because it will spit out the password to the auto-created admin account.
 
-alternatively, if you already had porom running before, put the db file (`db.prod.sqlite`) in `data/db` and it will Just Work.
+6. point your favorite proxy at `localhost:8080`
 
 ## manual (development)
-1. install python >= 3.11, sqlite3, libargon2, and imagemagick & clone repo
+1. install python >= 3.13, sqlite3, libargon2, and imagemagick & clone repo
 2. create a venv:
 
 ```bash
diff --git a/config/pyrom_config.toml.example b/config/pyrom_config.toml.example
index c9b1381..6b0a789 100644
--- a/config/pyrom_config.toml.example
+++ b/config/pyrom_config.toml.example
@@ -1,11 +1,31 @@
+### REQUIRED CONFIGURATION
+## the following settings are required.
+## the app will not work if they are missing.
+
+# the domain name you will be serving Pyrom from, without the scheme, including the subdomain(s).
+# this is overridden by the app in development.
+# used for generating URLs.
+# the app will not start if this field is missing.
+SERVER_NAME = "forum.your.domain"
+
+### OPTIONAL CONFIGURATION
+## the following settings are set to their default values.
+## you can override any of them.
+
+# your forum's name, shown on the header.
 SITE_NAME = "Pyrom"
-DISABLE_SIGNUP = false # if true, no one can sign up.
+
+# if true, users can not sign up manually. see the following two settings.
+DISABLE_SIGNUP = false
 
 # if neither of the following two options is true,
 # no one can sign up. this may be useful later when/if LDAP is implemented.
 
-MODS_CAN_INVITE = true # if true, allows moderators to create invite links. useless unless DISABLE_SIGNUP to be true.
-USERS_CAN_INVITE = false # if true, allows users to create invite links. useless unless DISABLE_SIGNUP to be true.
+# if true, allows moderators to create invite links. useless unless DISABLE_SIGNUP is true.
+MODS_CAN_INVITE = true
+
+# if true, allows users to create invite links. useless unless DISABLE_SIGNUP is true.
+USERS_CAN_INVITE = false
 
 # contact information, will be shown in /guides/contact
 # some babycodes allowed