From e46893e0b400ed75d64b29dd8f94d9d28917e9da Mon Sep 17 00:00:00 2001 From: "Troll (Hermes Agent)" Date: Mon, 3 Aug 2026 00:11:41 +0000 Subject: [PATCH] docs: update comments, docstrings, README, REVIEW, and env docs to match current features --- .env.example | 11 +++++++++-- Dockerfile | 3 +++ config.py | 28 ++++++++++++++++++++++------ docker-compose.yml | 5 +++++ init_db.py | 2 +- models.py | 6 +++++- templates/admin/dashboard.html | 4 ++-- templates/admin/request.html | 8 +++++--- templates/admin/settings.html | 5 +++-- templates/player.html | 10 +++++----- templates/request.html | 5 +++-- templates/status.html | 3 ++- 12 files changed, 65 insertions(+), 25 deletions(-) diff --git a/.env.example b/.env.example index 542b7d2..f9593af 100644 --- a/.env.example +++ b/.env.example @@ -11,12 +11,18 @@ # PUBLIC_BASE_URL - public HTTPS URL customers will use (e.g. https://booth.example.com) # # Optional: -# BOOTH_NAME - name shown in emails +# BOOTH_NAME - name shown in emails and customer text (default Trollgorithm Theme Songs) # HOST_PORT - host-side port mapping for docker-compose (default 127.0.0.1:8000) # INTERNAL_PORT - port gunicorn binds inside the container (default 8000) # PRICE_PER_VERSION - shown on the receipt page (default 10.00) # CURRENCY - currency label (default CAD) -# ADMIN_ALERT_EMAIL - unused; dashboard is the operator queue +# MAX_REVISIONS - default customer revision limit (default 2) +# DATABASE - SQLite database path inside the container (default /app/data/booth.db) +# UPLOAD_FOLDER - directory for uploaded MP3s inside the container (default /app/uploads) +# SMTP_HOST - outgoing mail server (default mailroot8.namespro.ca) +# SMTP_PORT - outgoing mail server port (default 465) +# SMTP_USER - SMTP login username (default ai@hallsworth.ca) +# SMTP_FROM - From address for customer emails (default ai@hallsworth.ca) APP_SECRET_KEY=change-me-in-production ADMIN_PASSWORD=change-me @@ -32,5 +38,6 @@ INTERNAL_PORT=8000 HOST_PORT=127.0.0.1:8000 PRICE_PER_VERSION=10.00 CURRENCY=CAD +MAX_REVISIONS=2 DATABASE=/app/data/booth.db UPLOAD_FOLDER=/app/uploads diff --git a/Dockerfile b/Dockerfile index 11c8e69..62e6905 100644 --- a/Dockerfile +++ b/Dockerfile @@ -10,6 +10,9 @@ # 4. Copy the entire repo into /app. # 5. Create an unprivileged user (boothuser) and data/upload directories. # 6. Expose the default internal port and run gunicorn on $INTERNAL_PORT. +# +# Environment: expects INTERNAL_PORT (default 8000) and the variables listed +# in config.py/.env.example to be supplied at runtime by docker-compose. FROM python:3.12-slim diff --git a/config.py b/config.py index cd75451..543808c 100644 --- a/config.py +++ b/config.py @@ -3,14 +3,30 @@ config.py ========= Configuration object loaded by Flask from environment variables. -Most operational settings are now editable at runtime from /admin/settings -and stored in booth_settings.json on disk. Sensitive email credentials are +Most operational settings are editable at runtime from /admin/settings and +stored in booth_settings.json on disk. Sensitive values (SMTP password) are encrypted with the Flask SECRET_KEY when saved. -Required environment values: - - APP_SECRET_KEY (used to sign sessions and encrypt stored settings) - - ADMIN_PASSWORD (plain-text login password) - - PUBLIC_BASE_URL +Environment variables (defaults shown): + Required: + - APP_SECRET_KEY long random string for Flask sessions and encryption + - ADMIN_PASSWORD plain-text password for /admin login + - PUBLIC_BASE_URL public URL customers use (e.g. https://booth.example.com) + - SMTP_PASS password for the SMTP account + Optional: + - BOOTH_NAME name in customer text and emails (default Trollgorithm Theme Songs) + - HOST_PORT docker-compose host-side port mapping (default 127.0.0.1:8000) + - INTERNAL_PORT gunicorn port inside the container (default 8000) + - MAX_REVISIONS default customer revision limit (default 2) + - PRICE_PER_VERSION price shown to customers (default 10.00) + - CURRENCY currency label (default CAD) + - DATABASE SQLite database path inside the container (default /app/data/booth.db) + - UPLOAD_FOLDER directory for uploaded MP3s inside the container (default /app/uploads) + - SETTINGS_FILE runtime settings JSON filename (default booth_settings.json) + - SMTP_HOST outgoing mail server (default mailroot8.namespro.ca) + - SMTP_PORT outgoing mail server port (default 465) + - SMTP_USER SMTP login username (default ai@hallsworth.ca) + - SMTP_FROM From address for customer emails (default ai@hallsworth.ca) """ import os diff --git a/docker-compose.yml b/docker-compose.yml index 73745d5..f2917cc 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -8,6 +8,11 @@ # Environment variables section. The container uses them directly, # so no .env file is required on disk. # +# Required: APP_SECRET_KEY, ADMIN_PASSWORD, SMTP_PASS, PUBLIC_BASE_URL +# Optional: BOOTH_NAME, HOST_PORT, INTERNAL_PORT, PRICE_PER_VERSION, +# CURRENCY, MAX_REVISIONS, DATABASE, UPLOAD_FOLDER, SMTP_HOST, +# SMTP_PORT, SMTP_USER, SMTP_FROM +# # Named volumes keep the SQLite database and uploaded MP3s persistent # across container restarts and redeploys. diff --git a/init_db.py b/init_db.py index a445cc6..a337c38 100644 --- a/init_db.py +++ b/init_db.py @@ -6,7 +6,7 @@ Standalone script to create the SQLite database tables. Run this once inside the container after deployment: python init_db.py -Or use the Flask CLI command: +Or use the registered Flask CLI command: flask --app app init-db """ diff --git a/models.py b/models.py index c094311..1c0787f 100644 --- a/models.py +++ b/models.py @@ -9,7 +9,11 @@ application context (`g`) is used to manage one connection per request. Schema overview (see SCHEMA constant): - requests table stores customer data, generated prompts, file paths, approval state, email timestamps, payment reference, player token, - vocal gender preference, revision count, and revision notes. + vocal gender preference, revision count, revision note, and operator notes. +- Revisions: when a customer requests changes, the current A/B MP3 files are + renamed to archived "RevN-" copies and new versions are uploaded later. +- operator_notes is an internal column for the booth team and is never shown + to customers. - Indexes on status and player_token for fast queue/lookup. """ diff --git a/templates/admin/dashboard.html b/templates/admin/dashboard.html index 54812b9..2efa4f5 100644 --- a/templates/admin/dashboard.html +++ b/templates/admin/dashboard.html @@ -10,8 +10,8 @@