documentation and env changes
This commit is contained in:
@@ -1,47 +0,0 @@
|
||||
# Setup
|
||||
|
||||
## Prerequisites
|
||||
- Docker + Docker Compose
|
||||
- Spotify Developer account (for a Client ID/Secret)
|
||||
|
||||
## Start services
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
## Database
|
||||
```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
|
||||
```
|
||||
|
||||
### Switching database drivers
|
||||
- `DATABASE_DRIVER=postgres` (default) continues to use the Postgres 16 service from `docker-compose.yml` and reads credentials from `DATABASE_URL`.
|
||||
- `DATABASE_DRIVER=sqlite` runs Doctrine against a local SQLite file at `var/data/database.sqlite`. `DATABASE_URL` is ignored; override the SQLite file path with `DATABASE_SQLITE_PATH` if desired.
|
||||
|
||||
## Admin user
|
||||
```bash
|
||||
docker compose exec php php bin/console app:promote-admin you@example.com
|
||||
```
|
||||
|
||||
## Moderator (optional)
|
||||
```bash
|
||||
docker compose exec php php bin/console app:promote-moderator mod@example.com
|
||||
```
|
||||
|
||||
## Spotify credentials
|
||||
- Prefer admin UI: open `/admin/settings` and enter Client ID/Secret. (Stored in DB)
|
||||
- Fallback to env vars:
|
||||
```bash
|
||||
export SPOTIFY_CLIENT_ID=your_client_id
|
||||
export SPOTIFY_CLIENT_SECRET=your_client_secret
|
||||
```
|
||||
|
||||
## Optional feature flags
|
||||
- Disable public registration by setting an env variable before starting Symfony:
|
||||
```bash
|
||||
export APP_ALLOW_REGISTRATION=0 # set to 1 (default) to re-enable
|
||||
```
|
||||
|
||||
|
||||
@@ -1,16 +0,0 @@
|
||||
# Features
|
||||
|
||||
- Spotify album search with Advanced filters (album, artist, year range)
|
||||
- Album page with details, list of reviews, and inline new review
|
||||
- Review rating slider (1–10) with live badge
|
||||
- Per-album aggregates: average rating and total review count
|
||||
- Auth modal (Login/Sign up) with remember-me cookie
|
||||
- Role-based access (user, moderator, admin) with protected admin routes
|
||||
- Admin Site Settings to manage Spotify credentials
|
||||
- Moderator/Admin dashboard with latest activity snapshots
|
||||
- User management table (create/delete accounts, promote/demote moderators)
|
||||
- User Dashboard for profile changes (email, display name, password)
|
||||
- Light/Dark theme toggle (cookie-backed)
|
||||
- Bootstrap UI
|
||||
|
||||
|
||||
@@ -1,38 +0,0 @@
|
||||
# Authentication & Users
|
||||
|
||||
## Modal auth
|
||||
- Login and registration happen in a Bootstrap modal.
|
||||
- AJAX submits keep users on the same page; state updates after reload.
|
||||
- Remember-me cookie keeps users logged in across sessions.
|
||||
|
||||
## Roles
|
||||
- `ROLE_USER`: default for registered users.
|
||||
- `ROLE_MODERATOR`: promoted via console `app:promote-moderator`, or via webUI; can manage users and all reviews/albums but not site settings.
|
||||
- `ROLE_ADMIN`: promoted via console `app:promote-admin`; includes moderator abilities plus site settings access.
|
||||
|
||||
### Demo accounts
|
||||
- Generate placeholder accounts locally with `php bin/console app:seed-demo-users --count=50` (default password: `password`).
|
||||
- Emails use the pattern `demo+<token>@example.com`, making them easy to spot in the admin UI.
|
||||
- Give existing accounts avatars with `php bin/console app:seed-user-avatars`; pass `--overwrite` to refresh everyone or tweak `--style` to try other DiceBear sets.
|
||||
|
||||
### Access flow
|
||||
- Visiting `/admin/dashboard`, `/admin/users`, or `/admin/settings` while unauthenticated forces a redirect through `/login`, which re-opens the modal automatically.
|
||||
- Moderators inherit all `ROLE_USER` permissions; admins inherit both moderator and user permissions via the role hierarchy.
|
||||
- Admin-only actions (site settings, moderator toggling, deleting other admins) are additionally guarded in controllers/templates to avoid accidental misuse.
|
||||
|
||||
### User management UI
|
||||
- `/admin/users` (moderator+) lists every account along with album/review counts.
|
||||
- Moderators can create new accounts (without affecting their own login session.. ).
|
||||
- Delete buttons are disabled (with tooltip hints) for protected rows such as the current user or any admin.
|
||||
- Admins see a Promote/Demote toggle: promoting grants `ROLE_MODERATOR`; demoting removes that role unless the target is an admin (admins always outrank moderators).
|
||||
- Admins can disable public registration from `/admin/settings`; when disabled, the “Sign up” button in the auth modal is replaced with a tooltip explaining that registration is closed, but `/admin/users` remains fully functional.
|
||||
- Registration can also be enforced via `APP_ALLOW_REGISTRATION=0/1` in the environment; the DB setting syncs on each Symfony boot, so flips take effect after the next restart.
|
||||
|
||||
## Password changes
|
||||
- On `/profile`, users can change email/display name.
|
||||
- To set a new password, the current password must be provided.
|
||||
|
||||
## Logout
|
||||
- `/logout` (link in user menu).
|
||||
|
||||
|
||||
@@ -1,20 +0,0 @@
|
||||
# Spotify Integration
|
||||
|
||||
## Credentials
|
||||
- Prefer configuring via `/admin/settings` (stored in DB).
|
||||
- Fallback to environment variables `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`.
|
||||
|
||||
## API client
|
||||
- `src/Service/SpotifyClient.php`
|
||||
- Client Credentials token fetch (cached)
|
||||
- `searchAlbums(q, limit)`
|
||||
- `getAlbum(id)` / `getAlbums([ids])`
|
||||
- `getAlbumWithTracks(id)` fetches metadata plus a hydrated tracklist
|
||||
- `getAlbumTracks(id)` provides the raw paginated track payload when needed
|
||||
|
||||
## Advanced search
|
||||
- The search page builds Spotify fielded queries:
|
||||
- `album:"..."`, `artist:"..."`, `year:YYYY` or `year:YYYY-YYYY`
|
||||
- Optional free-text added to the query
|
||||
|
||||
|
||||
@@ -1,22 +0,0 @@
|
||||
# Reviews & Albums
|
||||
|
||||
## Album page
|
||||
- Shows album artwork, metadata, average rating and review count.
|
||||
- Displays the full Spotify tracklist (duration, ordering, preview links) when available.
|
||||
- Lists reviews newest-first.
|
||||
- Logged-in users can submit a review inline.
|
||||
|
||||
## Permissions
|
||||
- Anyone can view.
|
||||
- Authors can edit/delete their own reviews.
|
||||
- Moderators and admins can edit/delete any review or user-created album.
|
||||
|
||||
## UI
|
||||
- Rating uses a slider (1–10) with ticks; badge shows current value.
|
||||
|
||||
## Demo data
|
||||
- Quickly create placeholder catalog entries with `php bin/console app:seed-demo-albums --count=40`. Add `--attach-users` to assign random existing users as album owners so the admin dashboard shows activity immediately.
|
||||
- Populate sample reviews with `php bin/console app:seed-demo-reviews --cover-percent=70 --max-per-album=8` so album stats and the admin dashboard have activity.
|
||||
- Use `--only-empty` when you want to focus on albums that currently have no reviews.
|
||||
|
||||
|
||||
@@ -1,20 +0,0 @@
|
||||
# Troubleshooting
|
||||
|
||||
## Cannot find template or routes
|
||||
- Clear cache: `docker compose exec php php bin/console cache:clear`
|
||||
- List routes: `docker compose exec php php bin/console debug:router`
|
||||
|
||||
## Missing vendors
|
||||
- Install: `docker compose exec php composer install --no-interaction --prefer-dist`
|
||||
|
||||
## .env not read in container
|
||||
- Ensure we mount `.env` or set env vars in compose; we mount `.env` in `docker-compose.yml`.
|
||||
|
||||
## Login modal shows blank
|
||||
- Make sure Bootstrap JS loads before the modal script (handled in `base.html.twig`).
|
||||
|
||||
## Hitting admin routes redirects to home
|
||||
- Expected when not logged in or lacking the required role.
|
||||
- Ensure your user has `ROLE_MODERATOR` for `/admin/dashboard` or `/admin/users`, and `ROLE_ADMIN` for `/admin/settings`.
|
||||
- Use the console commands in `06-admin-and-settings.md` to grant roles.
|
||||
|
||||
@@ -42,4 +42,7 @@ docker compose exec php php bin/console app:promote-moderator user@example.com
|
||||
- `/settings` provides a dark/light mode toggle.
|
||||
- Preference saved in a cookie; applied via `data-bs-theme`.
|
||||
|
||||
|
||||
## Useful tips
|
||||
- Registration toggle can be locked by environment (`APP_ALLOW_REGISTRATION`), in which case the UI explains that the value is immutable.
|
||||
- Changing Spotify credentials in settings is effective immediately; no restart is required.
|
||||
- Admin UI actions are CSRF‑protected and role‑checked; if a button appears disabled, hover for a tooltip explanation.
|
||||
90
docs/architecture.md
Normal file
90
docs/architecture.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# Architecture
|
||||
|
||||
This project follows a conventional Symfony architecture with clear separation of concerns across controllers, entities, repositories, services, security, forms, and templates.
|
||||
|
||||
## Naming & reusability standards (PHP)
|
||||
|
||||
- **Classes**
|
||||
- **Controllers** end with `Controller` (e.g. `AlbumController`) and expose HTTP‑oriented actions with verb‑based method names (`search`, `show`, `edit`, `delete`).
|
||||
- **Services** are named by capability, not by caller, using nouns or noun‑phrases (e.g. `AlbumSearchService`, `ConsoleCommandRunner`, `RegistrationToggle`). When a service is tightly scoped to a third‑party, the integration appears in the name (e.g. `SpotifyClient`, `SpotifyMetadataRefresher`).
|
||||
- **Entities** are singular domain nouns (`Album`, `Review`, `User`) and avoid transport or UI details.
|
||||
- **Commands** describe what they do and the environment they are meant for (e.g. `SeedDemoUsersCommand`, `PromoteAdminCommand`).
|
||||
|
||||
- **Methods**
|
||||
- Use **verb‑based, intention‑revealing names** that describe *what* the method does, not *how* it is used (e.g. `refreshAllSpotifyAlbums()`, `resetCatalog()`, `runConsoleCommand()`, `isEnabled()`, `findAlbumByPublicId()`).
|
||||
- Accessors start with `get*`, `set*`, `is*` / `has*` for booleans (e.g. `getEnvOverride()`, `isSpotifyConfigured()`).
|
||||
- Avoid ambiguous names like `run()`, `handle()`, or `process()` without a clear domain object; prefer `runConsoleCommand()`, `handleAlbumCoverUpload()`, etc.
|
||||
|
||||
- **Variables & parameters**
|
||||
- Use **descriptive, domain‑level names** (e.g. `$albumRepository`, `$reviewCount`, `$spotifyAlbumPayload`) and avoid unclear abbreviations (`$em` is acceptable for `EntityManagerInterface` in local scope, but prefer full names for properties).
|
||||
- Booleans read naturally (`$isEnabled`, `$shouldQuerySpotify`, `$needsSync`).
|
||||
- Collections are pluralized (`$albums`, `$userReviews`, `$spotifyIds`).
|
||||
|
||||
- **Files & namespaces**
|
||||
- File names match their primary class name and follow PSR‑4 (e.g. `src/Service/AlbumSearchService.php` for `App\Service\AlbumSearchService`).
|
||||
- Helper classes that are not tied to HTTP or persistence live under `src/Service` or `src/Dto` with names that describe the abstraction, not the caller.
|
||||
|
||||
These conventions should be followed for all new PHP code and when refactoring existing classes to keep the codebase reusable and self‑documenting.
|
||||
|
||||
## High-level flow
|
||||
1. Visitors search for albums (Spotify) and view an album page
|
||||
2. Logged‑in users can write, edit, and delete reviews
|
||||
3. Moderators and admins can moderate content and manage users
|
||||
4. Admins configure site settings (Spotify credentials, registration toggle)
|
||||
|
||||
## Layers & components
|
||||
|
||||
### Controllers (`src/Controller/*`)
|
||||
- `AlbumController` — search, album detail, inline review creation
|
||||
- `ReviewController` — view, edit, and delete reviews
|
||||
- `AccountController` — profile, password, and user settings pages
|
||||
- `Admin/*` — site dashboard, user management, and settings
|
||||
- `RegistrationController`, `SecurityController` — sign‑up and login/logout routes
|
||||
|
||||
### Entities (`src/Entity/*`)
|
||||
- `User` — authentication principal and roles
|
||||
- `Album`, `AlbumTrack` — normalized album metadata and track list
|
||||
- `Review` — user‑authored review with rating and timestamps
|
||||
- `Setting` — key/value store for site configuration (e.g., Spotify credentials)
|
||||
|
||||
### Repositories (`src/Repository/*`)
|
||||
- Doctrine repositories for querying by domain (albums, tracks, reviews, settings, users)
|
||||
|
||||
### Forms (`src/Form/*`)
|
||||
- `RegistrationFormType`, `ReviewType`, `ChangePasswordFormType`, `ProfileFormType`, `SiteSettingsType`, etc.
|
||||
- Leverage Symfony validation constraints for robust server‑side validation
|
||||
|
||||
### Services (`src/Service/*`)
|
||||
- `SpotifyClient` — Client Credentials token management (cached) and API calls
|
||||
- `SpotifyMetadataRefresher`, `SpotifyGenreResolver` — helpers for richer album data
|
||||
- `CatalogResetService` — admin action to reset/sync catalog state safely
|
||||
- `ImageStorage` — avatar uploads and related image handling
|
||||
- `RegistrationToggle` — DB‑backed registration flag with env override
|
||||
|
||||
### Security (`config/packages/security.yaml`, `src/Security/*`)
|
||||
- Role hierarchy: `ROLE_ADMIN` ⊇ `ROLE_MODERATOR` ⊇ `ROLE_USER`
|
||||
- `ReviewVoter` — edit/delete permissions for review owners and privileged roles
|
||||
- Access control for `/admin/*` enforced via routes and controllers
|
||||
|
||||
### Views (`templates/*`)
|
||||
- Twig templates for pages and partials (`base.html.twig`, `album/*`, `review/*`, `account/*`, `admin/*`)
|
||||
- Auth modal in `templates/_partials/auth_modal.html.twig`
|
||||
- Navbar with role‑aware links in `templates/_partials/navbar.html.twig`
|
||||
|
||||
### DTOs (`src/Dto/*`)
|
||||
- Simple data transfer objects for admin tables and search results
|
||||
|
||||
## Data & persistence
|
||||
- SQLite by default for local/packaged deployments; Postgres supported via `DATABASE_URL`
|
||||
- Migrations run on startup by default (`RUN_MIGRATIONS_ON_START=1`)
|
||||
|
||||
## Error handling & UX
|
||||
- 404 for missing albums
|
||||
- Flash messages for success/error on actions
|
||||
- Disabled/tooltip states in admin UI for protected actions (e.g., cannot delete an admin)
|
||||
|
||||
## Testing & tooling
|
||||
- PHPUnit setup in `composer.json` (`phpunit/phpunit`), BrowserKit & CSS Selector for functional coverage
|
||||
- Web Profiler enabled in dev
|
||||
|
||||
|
||||
48
docs/auth-and-users.md
Normal file
48
docs/auth-and-users.md
Normal file
@@ -0,0 +1,48 @@
|
||||
# Authentication & Users
|
||||
|
||||
## Login & Registration (modal)
|
||||
- Login and sign‑up are handled in a Bootstrap modal.
|
||||
- AJAX submits keep users on the page; a successful login refreshes state.
|
||||
- Remember‑me cookie keeps users logged in across sessions.
|
||||
|
||||
## Roles & Permissions
|
||||
- `ROLE_USER` — default for registered users
|
||||
- `ROLE_MODERATOR` — can access dashboard and user management, and moderate content
|
||||
- `ROLE_ADMIN` — adds Site Settings access and moderator promotion/demotion
|
||||
|
||||
Promotion (from your host):
|
||||
```bash
|
||||
docker compose exec tonehaus php bin/console app:promote-moderator mod@example.com
|
||||
docker compose exec tonehaus php bin/console app:promote-admin admin@example.com
|
||||
```
|
||||
|
||||
### Access flow
|
||||
- Visiting `/admin/*` while unauthenticated redirects through `/login`, which reopens the modal.
|
||||
- Role hierarchy applies: Admin ⊇ Moderator ⊇ User.
|
||||
- Controllers, templates, and voters enforce privilege boundaries (e.g., site settings are admin‑only).
|
||||
|
||||
## Public registration toggle
|
||||
- Toggle in UI: `/admin/settings` (stored in DB)
|
||||
- Env override: `APP_ALLOW_REGISTRATION=0|1` (env has priority on each boot)
|
||||
- When disabled, the modal replaces “Sign up” with a tooltip explaining registration is closed. Staff can still create users via `/admin/users`.
|
||||
|
||||
## User management (moderator+)
|
||||
- `/admin/users` lists accounts with album/review counts and actions:
|
||||
- Create accounts inline (does not affect the current session)
|
||||
- Delete users (guards prevent deleting self or administrators)
|
||||
- Admins can Promote/Demote Moderator on non‑admins
|
||||
|
||||
## Profiles & Passwords
|
||||
- `/account/profile`: update email and display name
|
||||
- `/account/password`: change password (requires current password)
|
||||
|
||||
## Demo accounts & avatars
|
||||
```bash
|
||||
docker compose exec tonehaus php bin/console app:seed-demo-users --count=50
|
||||
docker compose exec tonehaus php bin/console app:seed-user-avatars --overwrite
|
||||
```
|
||||
|
||||
## Logout
|
||||
- Link in the user menu calls `/logout` (handled by Symfony security).
|
||||
|
||||
|
||||
70
docs/deployment.md
Normal file
70
docs/deployment.md
Normal file
@@ -0,0 +1,70 @@
|
||||
# Deployment
|
||||
|
||||
This application ships with an immutable, single‑container image that includes PHP‑FPM, Nginx, and your code. By default it uses SQLite and auto‑runs migrations on start.
|
||||
|
||||
## Build (locally)
|
||||
```bash
|
||||
docker build \
|
||||
--target=prod \
|
||||
-t tonehaus-app:latest \
|
||||
-f docker/php/Dockerfile \
|
||||
.
|
||||
```
|
||||
|
||||
## Run
|
||||
```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
|
||||
```
|
||||
|
||||
### Notes
|
||||
- Health endpoint: `GET /healthz` (e.g., `curl http://localhost:8080/healthz`)
|
||||
- Migrations: `RUN_MIGRATIONS_ON_START=1` by default (safe to re‑run)
|
||||
- Cache warmup is executed on boot; `APP_SECRET` is required
|
||||
|
||||
## Persistence options
|
||||
### SQLite (default)
|
||||
- Data file at `var/data/database.sqlite`
|
||||
- Use a volume for durability:
|
||||
```bash
|
||||
docker run -d \
|
||||
-v tonehaus_sqlite:/var/www/html/var/data \
|
||||
...
|
||||
```
|
||||
|
||||
### Postgres
|
||||
Provide `DATABASE_DRIVER=postgres` and a `DATABASE_URL`, e.g.:
|
||||
```
|
||||
postgresql://user:password@host:5432/dbname?serverVersion=16&charset=utf8
|
||||
```
|
||||
You can disable automatic migrations with `RUN_MIGRATIONS_ON_START=0` and run them manually:
|
||||
```bash
|
||||
docker exec tonehaus php bin/console doctrine:migrations:migrate --no-interaction
|
||||
```
|
||||
|
||||
## Environment variables
|
||||
- `APP_ENV` (`prod` recommended in production)
|
||||
- `APP_SECRET` (required; random string)
|
||||
- `SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`
|
||||
- `APP_ALLOW_REGISTRATION` (env override for public registration)
|
||||
- `DATABASE_DRIVER` (`sqlite` default, or `postgres`)
|
||||
- `DATABASE_URL` (when using Postgres)
|
||||
- `DATABASE_SQLITE_PATH` (optional)
|
||||
- `RUN_MIGRATIONS_ON_START` (default `1`)
|
||||
|
||||
## Reverse proxy / TLS
|
||||
- Place behind your ingress/proxy (e.g., Nginx, Traefik, or a cloud load balancer)
|
||||
- Terminate TLS at the proxy and forward to the container’s port 8080
|
||||
- Ensure proxy sends `X-Forwarded-*` headers
|
||||
|
||||
## Zero‑downtime tips
|
||||
- Build then run a new container alongside the old one, switch traffic at the proxy
|
||||
- Keep SQLite on a named volume, or use Postgres for shared state across replicas
|
||||
|
||||
|
||||
31
docs/features.md
Normal file
31
docs/features.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Features
|
||||
|
||||
## Albums & Reviews
|
||||
- Spotify album search with advanced filters (album, artist, year range)
|
||||
- Album page: cover art, metadata, full tracklist (when available)
|
||||
- Reviews list (newest first) and inline new review form (logged-in)
|
||||
- Rating slider (1–10) with live badge
|
||||
- Per‑album aggregates: average rating and total review count
|
||||
|
||||
## Authentication & Users
|
||||
- Bootstrap auth modal for login/sign-up with AJAX submits
|
||||
- Remember‑me cookie keeps users signed in
|
||||
- Roles: User, Moderator, Admin (see `docs/auth-and-users.md`)
|
||||
- Profile: update email, display name, and password (requires current password)
|
||||
|
||||
## Administration
|
||||
- Dashboard: latest reviews/albums and key counts (moderator+)
|
||||
- Users: create/delete users, promote/demote moderators (admin constraints)
|
||||
- Settings: manage Spotify credentials, toggle public registration (admin)
|
||||
|
||||
## Design & UX
|
||||
- Responsive Bootstrap UI
|
||||
- Light/Dark theme toggle (cookie-backed)
|
||||
- CSRF protection on forms
|
||||
- Access control via role hierarchy and security voters
|
||||
|
||||
## Screenshots (placeholders)
|
||||
- Search page — `docs/img/search.png` (optional)
|
||||
- Album page — `docs/img/album.png` (optional)
|
||||
- Admin dashboard — `docs/img/admin-dashboard.png` (optional)
|
||||
|
||||
31
docs/reviews-and-albums.md
Normal file
31
docs/reviews-and-albums.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Reviews & Albums
|
||||
|
||||
## Album page
|
||||
- Artwork, metadata, average rating, and review count
|
||||
- Full Spotify tracklist when available
|
||||
- Reviews list (newest first)
|
||||
- Inline new review form for logged‑in users
|
||||
|
||||
## Writing a review
|
||||
- Rating slider from 1–10
|
||||
- Title (max 160 chars) and body (20–5000 chars)
|
||||
- Server-side validation provides inline errors on failure
|
||||
- Successful submissions persist, flash a success message, and reload the album page
|
||||
|
||||
## Editing & deleting reviews
|
||||
- Authors can edit/delete their own reviews
|
||||
- Moderators/Admins can edit/delete any review
|
||||
- CSRF protection is required for deletion
|
||||
|
||||
## Aggregates
|
||||
- The album page computes:
|
||||
- Total number of reviews for the album
|
||||
- Average rating rounded to one decimal
|
||||
|
||||
## Demo data
|
||||
```bash
|
||||
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
|
||||
```
|
||||
- Use `--only-empty` to focus on albums that currently have no reviews.
|
||||
|
||||
63
docs/setup.md
Normal file
63
docs/setup.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# Setup
|
||||
|
||||
## Prerequisites
|
||||
- Docker + Docker Compose
|
||||
- Spotify Developer account (Client ID/Secret)
|
||||
- A unique `APP_SECRET` value in your environment (for prod builds)
|
||||
|
||||
## 1) Start the stack
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
App: `http://localhost:8085`
|
||||
Health: `http://localhost:8085/healthz`
|
||||
|
||||
## 2) Create an admin
|
||||
```bash
|
||||
docker compose exec tonehaus php bin/console app:promote-admin you@example.com
|
||||
```
|
||||
|
||||
## 3) Configure Spotify
|
||||
- Preferred: open `/admin/settings` and enter your Client ID/Secret (stored in DB)
|
||||
- Env fallback (in `.env` or your shell):
|
||||
```bash
|
||||
SPOTIFY_CLIENT_ID=your_client_id
|
||||
SPOTIFY_CLIENT_SECRET=your_client_secret
|
||||
```
|
||||
|
||||
## 4) (Optional) Seed demo data
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
## Database drivers
|
||||
- SQLite (default): set `DATABASE_DRIVER=sqlite` (default) — data stored at `var/data/database.sqlite`
|
||||
- Postgres: set `DATABASE_DRIVER=postgres` and provide `DATABASE_URL`
|
||||
- If you enable the commented `db` service in `docker-compose.yml`, a typical URL is:
|
||||
```
|
||||
postgresql://symfony:symfony@db:5432/symfony?serverVersion=16&charset=utf8
|
||||
```
|
||||
|
||||
## Environment variables
|
||||
- `APP_ENV=dev|prod`
|
||||
- `APP_SECRET=<random_string>`
|
||||
- `SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`
|
||||
- `APP_ALLOW_REGISTRATION=1|0` (env can override DB setting)
|
||||
- `DATABASE_DRIVER=sqlite|postgres`
|
||||
- `DATABASE_SQLITE_PATH` (optional)
|
||||
- `RUN_MIGRATIONS_ON_START=1|0` (default 1)
|
||||
|
||||
## Useful commands
|
||||
```bash
|
||||
# Symfony cache
|
||||
docker compose exec tonehaus php bin/console cache:clear
|
||||
|
||||
# Inspect routes
|
||||
docker compose exec tonehaus php bin/console debug:router
|
||||
|
||||
# Promote moderator
|
||||
docker compose exec tonehaus php bin/console app:promote-moderator mod@example.com
|
||||
```
|
||||
30
docs/spotify-integration.md
Normal file
30
docs/spotify-integration.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# Spotify Integration
|
||||
|
||||
## Credentials
|
||||
- Preferred: Manage in `/admin/settings` (persisted in DB; no restart required)
|
||||
- Env fallback: `SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`
|
||||
|
||||
## API Client
|
||||
- `src/Service/SpotifyClient.php`
|
||||
- Client Credentials token fetch with caching
|
||||
- `searchAlbums(q, limit)` — album search endpoint
|
||||
- `getAlbum(id)` / `getAlbums([ids])` — metadata fetch
|
||||
- `getAlbumWithTracks(id)` — metadata + hydrated tracklist
|
||||
- `getAlbumTracks(id)` — raw paginated tracks (when needed)
|
||||
|
||||
### Caching & Rate Limits
|
||||
- Access tokens are cached until expiry to avoid unnecessary auth calls.
|
||||
- Downstream requests should be mindful of Spotify rate limits; user actions are debounced in the UI and server calls are focused on album/track data needed by the current page.
|
||||
|
||||
## Advanced search syntax
|
||||
- Fielded queries are composed as:
|
||||
- `album:"..."`, `artist:"..."`, `year:YYYY` or `year:YYYY-YYYY`
|
||||
- Optional free text is appended to the query
|
||||
- Examples:
|
||||
- `album:"in rainbows" artist:"radiohead"`
|
||||
- `year:1999-2004 post rock`
|
||||
|
||||
## Admin settings
|
||||
- Update credentials in `/admin/settings`
|
||||
- Settings are stored in the database; `APP_ENV` reload or container restart is not required
|
||||
|
||||
46
docs/troubleshooting.md
Normal file
46
docs/troubleshooting.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# Troubleshooting
|
||||
|
||||
## Cannot find template or routes
|
||||
- Clear cache: `docker compose exec tonehaus php bin/console cache:clear`
|
||||
- List routes: `docker compose exec tonehaus php bin/console debug:router`
|
||||
|
||||
## Missing vendors
|
||||
- Install: `docker compose exec tonehaus composer install --no-interaction --prefer-dist`
|
||||
|
||||
## .env not read in container
|
||||
- Ensure we mount `.env` or set env vars in compose; we mount `.env` in `docker-compose.yml`.
|
||||
|
||||
## Login modal shows blank
|
||||
- Make sure Bootstrap JS loads before the modal script (handled in `base.html.twig`).
|
||||
|
||||
## Hitting admin routes redirects to home
|
||||
- Expected when not logged in or lacking the required role.
|
||||
- Ensure your user has `ROLE_MODERATOR` for `/admin/dashboard` or `/admin/users`, and `ROLE_ADMIN` for `/admin/settings`.
|
||||
- Use the console commands in `admin-and-settings.md` to grant roles.
|
||||
|
||||
## SQLite file permissions
|
||||
- The default SQLite path is `var/data/database.sqlite`.
|
||||
- If migrations fail at startup: ensure the `sqlite_data` volume is attached and the path is writable by the container user.
|
||||
|
||||
## Postgres connection issues
|
||||
- If you enable the `db` service in `docker-compose.yml`, verify `DATABASE_URL` matches the service name and credentials.
|
||||
- Example URL:
|
||||
```
|
||||
postgresql://symfony:symfony@db:5432/symfony?serverVersion=16&charset=utf8
|
||||
```
|
||||
|
||||
## Spotify errors
|
||||
- Verify credentials in `/admin/settings` or env vars `SPOTIFY_CLIENT_ID` / `SPOTIFY_CLIENT_SECRET`.
|
||||
- Client Credentials tokens are cached; if revoked, wait for expiry or restart the container.
|
||||
|
||||
## ARM64 Build
|
||||
|
||||
```bash
|
||||
sudo docker buildx build \
|
||||
--platform linux/arm64 \
|
||||
--target prod \
|
||||
-t tonehaus/tonehaus:dev-arm64 \
|
||||
-f docker/php/Dockerfile \
|
||||
. \
|
||||
--load
|
||||
```
|
||||
Reference in New Issue
Block a user