documentation and env changes

docs/troubleshooting.md

@@ -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
+```