Improve configuration docs

.env.example

@@ -1,7 +1,9 @@
-# In local development, copy this template to .env and add your own config.
-# In production, just set environment variables using this file as a guide.
+# In local development, copy this template to .env and set your own config.
+# In production, set environment variables using this file as a guide.
+# For documentation and default values, see `class Settings` in main.py.
+
+HOSTNAME="https://intact.sail.codes"
 
-HOSTNAME="localhost"
 DB_CONNECTION_STR="mongodb://localhost:27017/"
 DB_NAME="intact"
 

README.md

@@ -2,6 +2,11 @@
 
 This is the backend server for INTACT. It uses FastAPI and MongoDB.
 
+## Configuration
+
+Copy `.env.example` to `.env` and edit the file with your own configuration values.
+For documentation and defaults for each variable, see the `Settings` class in `main.py`.
+
 ## Set up for local dev
 
 `pyenv virtualenv 3.12.4 intact-backend`
@@ -12,8 +17,6 @@ This is the backend server for INTACT. It uses FastAPI and MongoDB.
 
 (or equivalent)
 
-Copy `.env.example` to `.env` and edit the `DB_CONNECTION_STR` and `DB_NAME` to connect to your preferred local/Dockerized Mongo DB. The `HOSTNAME` will determine the hostname in the study URLs given to participants, so should point to the front-end. `ADMIN_PASSWORD` is the password that researchers will use to interact with the backend (it is not e.g. a database admin password).
-
 Recommended: Set up your IDE or a pre-commit hook to Blacken files automatically.
 Otherwise, remember to Blacken everything manually before committing.
 
@@ -29,7 +32,9 @@ View admin page: go to http://localhost:8000/admin
 
 ## Or run a local compose stack
 
-`docker compose up` and go to http://localhost:1333/docs (OpenAPI) or http://localhost:1333/admin (admin page)
+`docker compose up` and go to http://localhost:1333/docs (OpenAPI) or http://localhost:1333/admin (admin page).
+
+You will probably want to delete/comment out the `backup` service for this use case.
 
 
 # Workflow

compose.yml

@@ -11,6 +11,7 @@ services:
       DB_NAME: ${DB_NAME}
       DB_CONNECTION_STR: ${DB_CONNECTION_STR}
       ADMIN_PASSWORD: ${ADMIN_PASSWORD}
+      CORS_FRONTEND_ORIGIN: ${CORS_FRONTEND_ORIGIN}
 
   mongo:
     image: mongo:8

main.py

@@ -18,13 +18,24 @@
 
 
 class Settings(BaseSettings):
-    hostname: str = "localhost"
+    # HOSTNAME defines the hostname in the study URLs which will be generated
+    # for the participants. It should be the hostname of the front-end.
+    hostname: str = "https://intact.sail.codes"
+
+    # Details for the MongoDB to be used by this server.
     db_connection_str: str = "mongodb://localhost:27017/"
     db_name: str = "intact"
 
+    # ADMIN_PASSWORD is the password that researchers will use to interact
+    # with this server (it is not e.g. a database admin password).
     admin_password: str = "password"
 
+    # Set allowed CORS origins.
+    # CORS_FRONTEND_ORIGIN should be set to the hostname of the front-end.
     cors_frontend_origin: str = "https://intact.sail.codes"
+    # For development purposes, you may want to set CORS_LOCALHOST_ORIGIN.
+    # Note that setting CORS_FRONTEND_ORIGIN *or* CORS_LOCALHOST_ORIGIN to "*"
+    # will allow *all* origins (localhost or otherwise).
     cors_localhost_origin: Union[str, None] = None
 
     # In development, read settings from .env.