From 4f948ca8279da901525e2b668a472fbc5b4d550f Mon Sep 17 00:00:00 2001
From: Zoe <19900057+vpsx@users.noreply.github.com>
Date: Mon, 7 Oct 2024 15:37:53 -0400
Subject: [PATCH] Improve configuration docs

---
 .env.example |  8 +++++---
 README.md    | 11 ++++++++---
 compose.yml  |  1 +
 main.py      | 13 ++++++++++++-
 4 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/.env.example b/.env.example
index e31ea3c..8e7c60e 100644
--- a/.env.example
+++ b/.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"
 
diff --git a/README.md b/README.md
index a264abc..a8ed0c8 100644
--- a/README.md
+++ b/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
diff --git a/compose.yml b/compose.yml
index aee71f1..2f16fa3 100644
--- a/compose.yml
+++ b/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
diff --git a/main.py b/main.py
index c1071b7..41d8923 100644
--- a/main.py
+++ b/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.