theme-song-booth/README.md

Theme Song Booth

Prototype web app for a convention booth where attendees request custom AI-generated theme songs.

Flow

1. Customer fills out the public request form at /request.
2. Operator generates a Suno Custom Mode prompt via Hermes and saves it in the admin detail page.
3. Operator generates two song versions in Suno and uploads the MP3s in admin.
4. Operator clicks Send Preview Link. Customer receives an email with a private player page.
5. Customer listens to Version A and Version B, then approves one/both or requests changes.
6. Operator sees the approval alert, collects payment via Square reader, then clicks Mark Paid & Deliver.
7. Customer receives the approved MP3(s) as email attachments.

Local Development

cd /home/jess/workspace/theme-song-booth
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
# Edit .env and set APP_SECRET_KEY, ADMIN_PASSWORD, SMTP_PASS, PUBLIC_BASE_URL
.venv/bin/python init_db.py
.venv/bin/python -m flask --app app run --host=0.0.0.0

Deployment with Portainer

The repo includes a docker-compose.yml that builds directly from GitLab, so Portainer can pull and deploy it as a stack.

1. Log in to your Portainer instance.
2. Go to Stacks → Add stack.
3. Choose Repository and paste:
   • URL: https://gitlab.hallsworth.ca/yrtria/theme-song-booth.git
   • Branch: main
   • Compose path: docker-compose.yml
4. Add environment variables directly in Portainer under Environment variables:
   • APP_SECRET_KEY — long random string
   • ADMIN_PASSWORD — password for /admin
   • SMTP_PASS — b3ZzD@eM!MkqVS8P
   • PUBLIC_BASE_URL — your HTTPS domain
   • HOST_PORT — default 127.0.0.1:8000
   • BOOTH_NAME — optional
5. Deploy the stack.
6. Open a console into the booth container and run once:

   python init_db.py
   

7. Point your reverse proxy at the HOST_PORT you chose (e.g. http://host-ip:8000).
8. Print the booth QR code pointing to https://your-domain/request.

Portainer Notes

• The docker-compose.yml uses named volumes (booth-data, booth-uploads) so Portainer handles persistence automatically.
• For a pre-built image instead of repo build, replace the build: block with an image: line pointing to your registry.
• Update the stack after each push to redeploy the latest code.

Files

• app.py — Flask application with public/admin routes and email logic.
• models.py — SQLite schema and helper functions.
• config.py — Configuration loaded from environment.
• templates/ — Jinja2 HTML templates.
• init_db.py — Standalone script to create the SQLite database.
• Dockerfile / docker-compose.yml — Container packaging for Portainer.