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

```bash
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_HASH, SMTP_PASS, PUBLIC_BASE_URL
.venv/bin/python init_db.py
.venv/bin/python -m flask --app app run --host=0.0.0.0
```

Generate an admin password hash with:

```bash
.venv/bin/python -c "from werkzeug.security import generate_password_hash; print(generate_password_hash('yourpassword'))"
```

## 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 in Portainer (or upload a `.env` file):
   - `APP_SECRET_KEY`
   - `ADMIN_PASSWORD_HASH`
   - `SMTP_PASS`
   - `PUBLIC_BASE_URL` (your HTTPS domain)
   - `ADMIN_ALERT_EMAIL`
5. Deploy the stack.
6. Open a console into the `booth` container and run once:
   ```bash
   python init_db.py
   ```
7. Point your reverse proxy (Nginx Proxy Manager, Traefik, Caddy, etc.) at `http://host-ip:8000` on the chosen domain.
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.