boris/tonehaus
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

documentation and env changes
All checks were successful
CI (Gitea) / php-tests (push) Successful in 10m8s
Details
CI (Gitea) / docker-image (push) Successful in 2m18s
Details

Browse Source
This commit is contained in:
George Wilkinson
2025-11-28 08:14:13 +00:00
parent f77f3a9e40
commit d52eb6bd81
59 changed files with 932 additions and 565 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
README.md
View File

@@ -1,8 +1,8 @@
# Tonehaus — Music Ratings
# Tonehaus — Music Ratings (Symfony 7)
Discover albums from Spotify, read and write reviews, and manage your account. Built with Symfony 7, Twig, Doctrine, and Bootstrap.
Discover albums via Spotify, write and manage reviews, and administer your site. Built with Symfony 7, Twig, Doctrine, and Bootstrap.
## Quick start
## Quick start (Docker Compose)
1) Start the stack
@@ -10,109 +10,66 @@ Discover albums from Spotify, read and write reviews, and manage your account. B
docker compose up -d --build
```
2) Create the database schema
2) Open the app
- App URL: `http://localhost:8085`
- Health: `http://localhost:8085/healthz`
3) Create your first admin
- Sign Up through Tonehaus
```bash
docker compose exec php php bin/console doctrine:database:create --if-not-exists
docker compose exec php php bin/console doctrine:migrations:diff --no-interaction
docker compose exec php php bin/console doctrine:migrations:migrate --no-interaction
docker compose exec tonehaus php bin/console app:promote-admin you@example.com
```
3) Promote an admin (to access Site Settings)
4) Configure Spotify
- Go to `http://localhost:8085/admin/settings` and enter your Spotify Client ID/Secret, or
- Set env vars in `.env`: `SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`
5) (Optional) Seed demo data
```bash
docker compose exec php php bin/console app:promote-admin you@example.com
docker compose exec tonehaus php bin/console app:seed-demo-users --count=50
docker compose exec tonehaus php bin/console app:seed-demo-albums --count=40 --attach-users
docker compose exec tonehaus php bin/console app:seed-demo-reviews --cover-percent=70 --max-per-album=8
```
4) Configure Spotify API credentials (admin only)
- Open `http://localhost:8000/admin/settings` and enter your Spotify Client ID/Secret.
- Alternatively, set env vars for the PHP container: `SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`.
5) Visit `http://localhost:8000` to search for albums.
6) (Optional) Seed demo data
```bash
docker compose exec php php bin/console app:seed-demo-users --count=50
docker compose exec php php bin/console app:seed-demo-albums --count=40 --attach-users
docker compose exec php php bin/console app:seed-demo-reviews --cover-percent=70 --max-per-album=8
```
## Production container (immutable)
The repository ships with a single-container production target that bundles PHP-FPM, Nginx, your code, and a self-contained SQLite database. The build bakes in the `APP_ENV=prod` flag so production-only Symfony config is used automatically, and no bind mounts are required at runtime.
1. Build the image (uses `docker/php/Dockerfile`'s `prod` stage):
```bash
docker build \
--target=prod \
-t tonehaus-app:latest \
-f docker/php/Dockerfile \
.
```
2. Run the container (listens on port 8080 inside the container):
```bash
docker run -d \
--name tonehaus \
-p 8080:8080 \
-e APP_ENV=prod \
-e APP_SECRET=change_me \
-e SPOTIFY_CLIENT_ID=your_client_id \
-e SPOTIFY_CLIENT_SECRET=your_client_secret \
tonehaus-app:latest
```
- The runtime defaults to `DATABASE_DRIVER=sqlite` and stores the database file inside the image at `var/data/database.sqlite`. On each boot the entrypoint runs Doctrine migrations (safe to re-run) so the schema stays current while the container filesystem remains immutable from the host's perspective.
- To point at Postgres (or any external database), override `DATABASE_DRIVER` and `DATABASE_URL` at `docker run` time and optionally disable auto-migration with `RUN_MIGRATIONS_ON_START=0`.
- Health endpoint: `GET /healthz` on the published port (example: `curl http://localhost:8080/healthz`).
- The entrypoint now also performs Symfony cache clear/warmup on startup, which requires `APP_SECRET` to be set; the container exits with an error if it is missing so misconfigured deployments are caught immediately.
3. Rebuild/redeploy by re-running the `docker build` command; no manual steps or bind mounts are involved.
## Continuous integration
- `.github/workflows/ci.yml` runs on pushes and pull requests targeting `main` or `prod`.
- Job 1 installs Composer deps, prepares a SQLite database, runs Doctrine migrations, and executes the PHPUnit suite under PHP 8.2 so functional regressions are caught early.
- Job 2 builds the production Docker image (`docker/php/Dockerfile` prod stage), checks that key Symfony artifacts (e.g., `public/index.php`, `bin/console`) are present, ensures `APP_ENV=prod` is baked in, and smoke-tests the `/entrypoint.sh` startup path.
- The resulting artifact mirrors the immutable container described above, so a green CI run guarantees the repo can be deployed anywhere via `docker run`.
- Self-hosted runners can use `.gitea/workflows/ci.yml`, which mirrors the GitHub workflow but also supports optional registry pushes after the image passes the same verification steps.
## Database driver
- Set `DATABASE_DRIVER=postgres` (default) to keep using the Postgres 16 container defined in `docker-compose.yml`.
- Set `DATABASE_DRIVER=sqlite` to run against a self-contained SQLite file stored at `var/data/database.sqlite`.
- When `DATABASE_DRIVER=sqlite`, the `DATABASE_URL` env var is ignored. Doctrine will automatically create and use the SQLite file; override the default location with `DATABASE_SQLITE_PATH` if needed.
Notes:
- The packaged image uses SQLite by default and runs Doctrine migrations on start (idempotent).
- To switch to Postgres, set `DATABASE_DRIVER=postgres` and provide `DATABASE_URL`.
## Features
- Spotify search with Advanced filters (album, artist, year range) and per-album aggregates (avg/count)
- Album page with details, reviews list, and inline new review (logged in)
- Auth modal (Login/Sign up) with remember-me cookie, no separate pages
- Role-based access: authors manage their own reviews, admins can manage any
- Admin Site Settings to manage Spotify credentials in DB
- User Dashboard to update profile and change password (requires current password)
- Light/Dark theme toggle in Settings (cookie-backed)
- Bootstrap UI
- Spotify search with advanced filters (album, artist, year range) and per‑album aggregates (avg/count)
- Album page with details, tracklist, reviews list, and inline new review (logged-in)
- Auth modal (Login/Sign up) with remember‑me; no separate pages
- Role-based access: authors manage their own reviews; moderators/admins can moderate content
- Admin Site Settings: manage Spotify credentials and public registration toggle
- User Dashboard: profile updates and password change
- Light/Dark theme toggle (cookie-backed)
## Rate limiting & caching
## Documentation
- Server-side Client Credentials; access tokens are cached.
- Setup and configuration: `docs/setup.md`
- Feature overview: `docs/features.md`
- Authentication and users: `docs/auth-and-users.md`
- Spotify integration: `docs/spotify-integration.md`
- Reviews and albums: `docs/reviews-and-albums.md`
- Admin & site settings: `docs/admin-and-settings.md`
- Troubleshooting: `docs/troubleshooting.md`
- Architecture: `docs/architecture.md`
- Deployment: `docs/deployment.md`
## Docs
## Environment overview
See `/docs` for how-tos and deeper notes:
- Setup and configuration: `docs/01-setup.md`
- Features and UX: `docs/02-features.md`
- Authentication and users: `docs/03-auth-and-users.md`
- Spotify integration: `docs/04-spotify-integration.md`
- Reviews and albums: `docs/05-reviews-and-albums.md`
- Admin & site settings: `docs/06-admin-and-settings.md`
- Troubleshooting: `docs/07-troubleshooting.md`
- `APP_ENV` (dev|prod), `APP_SECRET` (required)
- `SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`
- `APP_ALLOW_REGISTRATION` (1|0) — DB setting can be overridden by env
- `DATABASE_DRIVER` (sqlite|postgres), `DATABASE_URL` (when using Postgres)
- `DATABASE_SQLITE_PATH` (optional, defaults to `var/data/database.sqlite`)
- `RUN_MIGRATIONS_ON_START` (1|0, defaults to 1)
## License