mirror of
https://github.com/maxdorninger/MediaManager.git
synced 2026-04-21 13:25:14 +02:00
reformat docs for consistency
This commit is contained in:
maxDorninger
@@ -13,24 +13,32 @@ This section is for those who want to contribute to Media Manager or understand
|
||||
|
||||
### Environment Variables
|
||||
|
||||
MediaManager uses various environment variables for configuration. In the Docker development setup (`docker-compose.dev.yaml`), most of these are automatically configured for you.
|
||||
MediaManager uses various environment variables for configuration. In the Docker development setup (
|
||||
`docker-compose.dev.yaml`), most of these are automatically configured for you.
|
||||
|
||||
#### Backend Variables
|
||||
|
||||
- `BASE_PATH`: Sets the base path for the app (e.g., for subdirectory deployments)
|
||||
- `PUBLIC_VERSION`: Version string displayed in `/api/v1/health` endpoint
|
||||
- `FRONTEND_FILES_DIR`: Directory for built frontend files (e.g., `/app/web/build` in Docker)
|
||||
- `MEDIAMANAGER_MISC__DEVELOPMENT`: When set to `TRUE`, enables FastAPI hot-reloading in Docker
|
||||
|
||||
#### Frontend Variables
|
||||
|
||||
- `PUBLIC_API_URL`: API URL for backend communication (automatically configured via Vite proxy in Docker)
|
||||
- `PUBLIC_VERSION`: Version string displayed in the frontend UI
|
||||
- `BASE_PATH`: Base path for frontend routing (matches backend BASE_PATH)
|
||||
|
||||
#### Docker Development Variables
|
||||
|
||||
- `DISABLE_FRONTEND_MOUNT`: When `TRUE`, disables mounting built frontend files (allows separate frontend container)
|
||||
- **Note:** This is automatically set in `docker-compose.dev.yaml` to enable the separate frontend development container
|
||||
|
||||
<tip>
|
||||
This is automatically set in <code>docker-compose.dev.yaml</code> to enable the separate frontend development container
|
||||
</tip>
|
||||
|
||||
#### Configuration Files
|
||||
|
||||
- Backend: `res/config/config.toml` (created from `config.dev.toml`)
|
||||
- Frontend: `web/.env` (created from `.env.example`)
|
||||
|
||||
@@ -62,22 +70,27 @@ features.
|
||||
### Recommended Development Workflow
|
||||
|
||||
The **recommended way** to develop MediaManager is using the fully Dockerized setup with `docker-compose.dev.yaml`.
|
||||
This ensures you're working in the same environment as production and makes it easy for new contributors to get started without installing Python, Node.js, or other dependencies locally.
|
||||
This ensures you're working in the same environment as production and makes it easy for new contributors to get started
|
||||
without installing Python, Node.js, or other dependencies locally.
|
||||
|
||||
The development environment includes:
|
||||
|
||||
- **Backend (FastAPI)** with automatic hot-reloading for Python code changes
|
||||
- **Frontend (SvelteKit/Vite)** with Hot Module Replacement (HMR) for instant updates
|
||||
- **Database (PostgreSQL)** pre-configured and ready to use
|
||||
|
||||
**What requires what:**
|
||||
- **Python code changes (.py files)**: Automatically detected and hot-reloaded, no action needed ✨
|
||||
- **Frontend code changes (.svelte, .ts, .css)**: Instant HMR updates in browser, no action needed ✨
|
||||
- **Configuration changes (config.toml)**: Live updates via volume mount, no action needed ✨
|
||||
- **Backend dependencies (pyproject.toml)**: Require rebuilding: `docker compose -f docker-compose.dev.yaml build mediamanager`
|
||||
- **Frontend dependencies (package.json)**: Restart frontend container: `docker compose -f docker-compose.dev.yaml restart frontend`
|
||||
- **Database migrations**: Automatically run on backend container startup
|
||||
#### What supports hot reloading and what does not
|
||||
|
||||
This approach eliminates the need for container restarts during normal development and provides the best developer experience with instant feedback for code changes.
|
||||
- Python code changes (.py files), Frontend code changes (.svelte, .ts, .css) and configuration changes (config.toml)
|
||||
reload automatically.
|
||||
- Changing the backend dependencies (pyproject.toml) requires rebuilding:
|
||||
`docker compose -f docker-compose.dev.yaml build mediamanager`
|
||||
- Changing the frontend dependencies (package.json) requires restarting the frontend container:
|
||||
`docker compose -f docker-compose.dev.yaml restart frontend`
|
||||
- Database migrations: Automatically run on backend container startup
|
||||
|
||||
This approach eliminates the need for container restarts during normal development and provides the best developer
|
||||
experience with instant feedback for code changes.
|
||||
|
||||
#### How the Frontend Connects to the Backend
|
||||
|
||||
@@ -87,19 +100,21 @@ In the Docker development setup, the frontend and backend communicate through Vi
|
||||
- **Backend runs on**: `http://mediamanager:8000` (Docker internal network)
|
||||
- **Vite proxy**: Automatically forwards all `/api/*` requests from frontend to backend
|
||||
|
||||
This means when your browser makes a request to `http://localhost:5173/api/v1/tv/shows`, Vite automatically proxies it to `http://mediamanager:8000/api/v1/tv/shows`. The `PUBLIC_API_URL` environment variable is set to use this proxy, so you don't need to configure anything manually.
|
||||
This means when your browser makes a request to `http://localhost:5173/api/v1/tv/shows`, Vite automatically proxies it
|
||||
to `http://mediamanager:8000/api/v1/tv/shows`. The `PUBLIC_API_URL` environment variable is set to use this proxy, so
|
||||
you don't need to configure anything manually.
|
||||
|
||||
### Setting up the full development environment with Docker (Recommended)
|
||||
|
||||
This is the easiest and recommended way to get started. Everything runs in Docker with hot-reloading enabled.
|
||||
|
||||
1. **Copy the example config & .env:**
|
||||
1. Copy the example config & .env:
|
||||
```bash
|
||||
cp config.dev.toml res/config/config.toml
|
||||
cp web/.env.example web/.env
|
||||
```
|
||||
|
||||
2. **Start all services:**
|
||||
2. Start all services:
|
||||
```bash
|
||||
# Recommended: Use make commands for easy development
|
||||
make up
|
||||
@@ -108,14 +123,16 @@ This is the easiest and recommended way to get started. Everything runs in Docke
|
||||
docker compose -f docker-compose.dev.yaml up
|
||||
```
|
||||
|
||||
**Tip:** Run `make help` to see all available development commands including `make down`, `make logs`, `make app` (shell into backend), and more.
|
||||
<tip> Run <code>make help</code> to see all available development commands including <code>make down</code>, <code>make logs</code>, <code>make app</code> (
|
||||
shell into backend), and more.</tip>
|
||||
|
||||
3. **Access the application:**
|
||||
- Frontend (with HMR): http://localhost:5173
|
||||
- Backend API: http://localhost:8000
|
||||
- Database: localhost:5432
|
||||
3. Access the application:
|
||||
- Frontend (with HMR): http://localhost:5173
|
||||
- Backend API: http://localhost:8000
|
||||
- Database: localhost:5432
|
||||
|
||||
That's it! Now you can edit code and see changes instantly:
|
||||
|
||||
- Edit Python files → Backend auto-reloads
|
||||
- Edit Svelte/TypeScript files → Frontend HMR updates in browser
|
||||
- Edit config.toml → Changes apply immediately
|
||||
@@ -155,8 +172,9 @@ That's it! Now you can edit code and see changes instantly:
|
||||
|
||||
### Setting up the frontend development environment (Local, Optional)
|
||||
|
||||
**Note:** Using the Docker setup above is recommended. This section is for those who prefer to run the frontend locally
|
||||
outside of Docker.
|
||||
<note>
|
||||
Using the Docker setup above is recommended. This section is for those who prefer to run the frontend locally outside of Docker.
|
||||
</note>
|
||||
|
||||
1. Clone the repository
|
||||
2. cd into repo root
|
||||
@@ -180,8 +198,8 @@ outside of Docker.
|
||||
6. Install the dependencies with npm: `npm install`
|
||||
7. Start the frontend development server: `npm run dev`
|
||||
|
||||
**Important:** If running frontend locally, make sure to add `http://localhost:5173` to the `cors_urls` in your backend
|
||||
config file.
|
||||
<tip>If running frontend locally, make sure to add <code>http://localhost:5173</code> to the <code>cors_urls</code> in your backend
|
||||
config file.</tip>
|
||||
|
||||
- Format the code with `npm run format`
|
||||
- Lint the code with `npm run lint`
|
||||
@@ -190,48 +208,60 @@ config file.
|
||||
|
||||
### Common Docker Development Issues
|
||||
|
||||
**Port already in use errors:**
|
||||
- Check if ports 5173, 8000, or 5432 are already in use: `lsof -i :5173` (macOS/Linux) or `netstat -ano | findstr :5173` (Windows)
|
||||
#### Port already in use errors
|
||||
|
||||
- Check if ports 5173, 8000, or 5432 are already in use: `lsof -i :5173` (macOS/Linux) or
|
||||
`netstat -ano | findstr :5173` (Windows)
|
||||
- Stop conflicting services or change ports in `docker-compose.dev.yaml`
|
||||
|
||||
**Container not showing code changes:**
|
||||
#### Container not showing code changes
|
||||
|
||||
- Verify volume mounts are correct in `docker-compose.dev.yaml`
|
||||
- For backend: Ensure `./media_manager:/app/media_manager` is mounted
|
||||
- For frontend: Ensure `./web:/app` is mounted
|
||||
- On Windows: Check that file watching is enabled in Docker Desktop settings
|
||||
|
||||
**Frontend changes not updating:**
|
||||
#### Frontend changes not updating
|
||||
|
||||
- Check that the frontend container is running: `make ps` or `docker compose -f docker-compose.dev.yaml ps`
|
||||
- Verify Vite's file watching is working (should see HMR updates in browser console)
|
||||
- Try restarting the frontend container: `docker compose -f docker-compose.dev.yaml restart frontend`
|
||||
|
||||
**Backend changes not reloading:**
|
||||
#### Backend changes not reloading
|
||||
|
||||
- Verify `MEDIAMANAGER_MISC__DEVELOPMENT=TRUE` is set in `docker-compose.dev.yaml`
|
||||
- Check backend logs: `make logs ARGS="--follow mediamanager"` or `docker compose -f docker-compose.dev.yaml logs -f mediamanager`
|
||||
- Check backend logs: `make logs ARGS="--follow mediamanager"` or
|
||||
`docker compose -f docker-compose.dev.yaml logs -f mediamanager`
|
||||
- If dependencies changed, rebuild: `docker compose -f docker-compose.dev.yaml build mediamanager`
|
||||
|
||||
**Database migration issues:**
|
||||
#### Database migration issues
|
||||
|
||||
- Migrations run automatically on container startup
|
||||
- To run manually: `make app` then `uv run alembic upgrade head`
|
||||
- To create new migration: `make app` then `uv run alembic revision --autogenerate -m "description"`
|
||||
|
||||
**Viewing logs:**
|
||||
#### Viewing logs
|
||||
|
||||
- All services: `make logs`
|
||||
- Follow logs in real-time: `make logs ARGS="--follow"`
|
||||
- Specific service: `make logs ARGS="mediamanager --follow"`
|
||||
|
||||
**Interactive debugging:**
|
||||
#### Interactive debugging
|
||||
|
||||
- Shell into backend: `make app` (or `docker compose -f docker-compose.dev.yaml exec -it mediamanager bash`)
|
||||
- Shell into frontend: `make frontend` (or `docker compose -f docker-compose.dev.yaml exec -it frontend sh`)
|
||||
- Once inside, you can run commands like `uv run alembic upgrade head`, `npm install`, etc.
|
||||
|
||||
**Volume permission issues (Linux):**
|
||||
#### Volume permission issues (Linux)
|
||||
|
||||
- Docker containers may create files as root, causing permission issues
|
||||
- Solution: Run containers with your user ID or use Docker's `user:` directive
|
||||
- Alternatively: `sudo chown -R $USER:$USER .` to reclaim ownership
|
||||
|
||||
**Complete reset:**
|
||||
#### Complete reset
|
||||
|
||||
If all else fails, you can completely reset your development environment:
|
||||
|
||||
```bash
|
||||
make down
|
||||
docker compose -f docker-compose.dev.yaml down -v # Remove volumes
|
||||
|
||||
Reference in New Issue
Block a user