starred/MediaManager-maxdorninger-1
1
0
Fork 0
mirror of https://github.com/maxdorninger/MediaManager.git synced 2026-04-17 15:43:28 +02:00
Code Issues Packages Projects Releases Wiki Activity

updating developer information/guide

Browse Source
This commit is contained in:
maxDorninger
2025-07-18 21:03:30 +02:00
parent cd8b3abf70
commit d352a8546a
3 changed files with 192 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
README.md
View File

@@ -97,36 +97,7 @@ See the [open issues](hhttps://maxdorninger.github.io/MediaManager/issues) for a
## Developer Quick Start
```bash
pip install uv
uv venv
# Activate the virtual environment
uv pip install -e .
```
```bash
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up db -d
```
```bash
uv run alembic upgrade head
```
### Get the frontend up and running
```bash
cd ./web && npm install
```
### Now start the backend and frontend
```bash
fastapi dev ./media_manager/main.py --reload --host
```
```bash
cd ./web && npm run dev
```
For the developer guide see the [Developer Guide](https://maxdorninger.github.io/MediaManager/developer-guide.html).
<!-- LICENSE -->

100
Writerside/topics/developer-guide.md
View File

@@ -2,35 +2,96 @@
This section is for those who want to contribute to Media Manager or understand its internals.
### Source Code
## Source Code directory structure
- `media_manager/`: Backend FastAPI application
- `web/`: Frontend SvelteKit application
- `Writerside/`: Documentation
- `metadata_relay/`: Metadata relay service
- `metadata_relay/`: Metadata relay service, also FastAPI
### Backend Development
- Uses `uv` for dependency management
- Follows standard FastAPI project structure
- Database migrations are handled by Alembic
### Frontend Development
- Uses `npm` for package management
- SvelteKit with TypeScript
### Further Configuration
## Special Dev Configuration
#### Env Variables
- `BASE_PATH`: this sets the base path for the app
- `PUBLIC_VERSION`: this sets the version variable
- `FRONTEND_FILES_DIR`: directory for frontend files, e.g. in Docker container it is `/app/web/build`
- `BASE_PATH`: this sets the base path for the app (can be set for both backend and frontend)
- `PUBLIC_VERSION`: this sets the version variable, it is displayed in the frontend (requires rebuilding of the
frontend) and in the /api/v1/health endpoint (can be set for both backend and frontend)
- `FRONTEND_FILES_DIR`: directory for frontend files, e.g. in Docker container it is `/app/web/build` (only backend)
### Contributing
## Contributing
- Consider opening an issue to discuss significant changes before starting work
- Consider opening an issue to discuss changes before starting work
## Setting up the Development Environment
I use IntellijIdea with the Pycharm and Webstorm plugins to develop this, but this guide should also work with VSCode.
Normally I'd recommend Intellij, but unfortunately only Intellij Ultimate has support for FastAPI and some other
features.
### Recommended VSCode Plugins:
- Python
- Svelte for VSCode
- and probably more, but I don't use VSCode myself, so I can't recommend anymore.
### Recommended Intellij/Pycharm Plugins:
- Python
- Svelte
- Pydantic
- Ruff
- VirtualKit
- Writerside (for writing documentation)
### Other recommendations
I recommend developing using Docker, i.e. you can use the provided `docker-compose.dev.yaml` file. This dev
docker-compose file has the `./media_manager` directory mounted at `/app/media_manager` in the container, meaning you
can run the code using the container in exactly the environment it will be running in.
Additionally, to develop the frontend I use a locally installed Node.js server. So basically a hybrid approach, where
the backend runs in a container and the frontend runs on Windows. To make this work, you need to make sure the
`cors_urls` and `frontend_url` are set correctly in the backend's config file.
Unfortunately, a side effect of this setup is that you have to rebuild the Docker image everytime when you change the
python dependencies in any way or at least restart the container if you change the code. For a fast-paced development it
may be more convenient to run the backend locally too, because then it supports hot reloading.
### Setting up the backend development environment
1. Clone the repository
2. cd into repo root
3. [Install `uv`.](https://docs.astral.sh/uv/getting-started/installation/)
4. run `uv --version` to verify that `uv` is installed correctly
5. Install python if you haven't already: `uv python install 3.13`
6. Create a virtual environment with uv: `uv venv --python 3.13`
7. Install dependencies: `uv sync`
8. run db migrations with `uv run alembic upgrade head`
9. run the backend with `uv run ./media_manager/main.py --reload --port 8000`
- format code with `uvx ruff format`
- lint code with `uvx ruff check`
### Setting up the frontend development environment
1. Clone the repository
2. cd into repo root
3. cd into `web` directory
4. install Node.js and npm if you haven't already, I
used [nvm-windows](https://github.com/coreybutler/nvm-windows?tab=readme-ov-file):
```powershell
nvm install 24.1.0
nvm use 24.1.0
```
I also needed to run the following command to be able to use `npm`:
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
5. Install the dependencies with npm: `npm install`
6. Start the frontend development server: `npm run dev`
- format the code with `npm run format`
- lint the code with `npm run lint`
## Sequence Diagrams
@@ -79,6 +140,7 @@ sequenceDiagram
- Python with FastAPI
- SQLAlchemy
- Pydantic and Pydantic-Settings
- Alembic
### Frontend

110
docker-compose.dev.yaml
View File

@@ -1,4 +1,114 @@
services:
db:
image: postgres:latest
restart: unless-stopped
container_name: postgres
volumes:
- ./res/postgres:/var/lib/postgresql/data
environment:
POSTGRES_USER: MediaManager
POSTGRES_DB: MediaManager
POSTGRES_PASSWORD: MediaManager
ports:
- "5432:5432"
mediamanager:
build:
context: .
dockerfile: Dockerfile
args:
- VERSION=locally-built
- BASE_PATH=
container_name: mediamanager
restart: unless-stopped
ports:
- "8000:8000"
environment:
- CONFIG_DIR=/data/config.toml
volumes:
#- ./web/build:/app/web/build # this is only needed to test built frontend when developing frontend
- ./res/data/:/data/images/
- ./res/:/data/
- ./media_manager:/app/media_manager
prowlarr:
image: lscr.io/linuxserver/prowlarr:latest
container_name: prowlarr
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
volumes:
- ./res/prowlarr:/config
restart: unless-stopped
ports:
- "9696:9696"
qbittorrent:
image: lscr.io/linuxserver/qbittorrent:latest
container_name: qbittorrent
environment:
- TZ=Etc/UTC
- WEBUI_PORT=8080
- TORRENTING_PORT=6881
ports:
- 8080:8080
- 6881:6881
- 6881:6881/udp
restart: unless-stopped
volumes:
- ./res/torrent:/download
- ./res/qbittorrent:/config
transmission:
image: lscr.io/linuxserver/transmission:latest
container_name: transmission
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
- USER=admin
- PASS=admin
volumes:
- ./res/transmission:/config
- ./res/torrents:/data/torrents
ports:
- 9091:9091
restart: unless-stopped
pocket-id:
image: ghcr.io/pocket-id/pocket-id
restart: unless-stopped
env_file: .env
ports:
- 1411:1411
volumes:
- ./res/pocket-id:/app/data
healthcheck:
test: "curl -f http://localhost:1411/healthz"
interval: 1m30s
timeout: 5s
retries: 2
start_period: 10s
sabnzbd:
image: lscr.io/linuxserver/sabnzbd:latest
container_name: sabnzbd
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
volumes:
- ./sabnzbd:/config
- ./torrent:/downloads
ports:
- 8081:8080
restart: unless-stopped
jackett:
image: lscr.io/linuxserver/jackett:latest
container_name: jackett
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
- AUTO_UPDATE=true
volumes:
- ./res/jackett/data:/config
- ./res/jackett/torrents:/downloads
ports:
- 9117:9117
restart: unless-stopped