diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 0000000..52c695d --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,107 @@ +name: Build documentation + +on: + push: + branches: [ "master" ] + paths: + - 'docs/**' + - '.github/workflows/build-docs.yml' + workflow_dispatch: + +permissions: + contents: read + id-token: write + pages: write + +env: + INSTANCE: 'Writerside/mm' + DOCKER_VERSION: '2025.04.8412' + +jobs: + build: + runs-on: ubuntu-latest + outputs: + algolia_artifact: ${{ steps.define-ids.outputs.algolia_artifact }} + artifact: ${{ steps.define-ids.outputs.artifact }} + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Define instance id and artifacts + id: define-ids + run: | + INSTANCE=${INSTANCE#*/} + INSTANCE_ID_UPPER=$(echo "$INSTANCE" | tr '[:lower:]' '[:upper:]') + ARTIFACT="webHelp${INSTANCE_ID_UPPER}2-all.zip" + ALGOLIA_ARTIFACT="algolia-indexes-${INSTANCE_ID_UPPER}.zip" + + # Print the values + echo "INSTANCE_ID_UPPER: $INSTANCE_ID_UPPER" + echo "ARTIFACT: $ARTIFACT" + echo "ALGOLIA_ARTIFACT: $ALGOLIA_ARTIFACT" + + # Set the environment variables and outputs + echo "INSTANCE_ID_UPPER=$INSTANCE_ID_UPPER" >> $GITHUB_ENV + echo "ARTIFACT=$ARTIFACT" >> $GITHUB_ENV + echo "ALGOLIA_ARTIFACT=$ALGOLIA_ARTIFACT" >> $GITHUB_ENV + echo "artifact=$ARTIFACT" >> $GITHUB_OUTPUT + echo "algolia_artifact=$ALGOLIA_ARTIFACT" >> $GITHUB_OUTPUT + + - name: Build docs using Writerside Docker builder + uses: JetBrains/writerside-github-action@v4 + with: + instance: ${{ env.INSTANCE }} + docker-version: ${{ env.DOCKER_VERSION }} + + - name: Save artifact with build results + uses: actions/upload-artifact@v4 + with: + name: docs + path: | + artifacts/${{ steps.define-ids.outputs.artifact }} + artifacts/report.json + artifacts/${{ steps.define-ids.outputs.algolia_artifact }} + retention-days: 7 + test: + needs: build + runs-on: ubuntu-latest + steps: + - name: Download artifacts + uses: actions/download-artifact@v4 + with: + name: docs + path: artifacts + + - name: Test documentation + uses: JetBrains/writerside-checker-action@v1 + with: + instance: ${{ env.INSTANCE }} + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + needs: [ build, test ] + runs-on: ubuntu-latest + steps: + - name: Download artifacts + uses: actions/download-artifact@v4 + with: + name: docs + path: artifacts + + - name: Unzip artifact + run: unzip -O UTF-8 -qq "artifacts/${{ needs.build.outputs.artifact }}" -d dir + + - name: Setup Pages + uses: actions/configure-pages@v4 + + - name: Package and upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: dir + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/Writerside/c.list b/Writerside/c.list new file mode 100644 index 0000000..c4c77a2 --- /dev/null +++ b/Writerside/c.list @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/Writerside/cfg/buildprofiles.xml b/Writerside/cfg/buildprofiles.xml new file mode 100644 index 0000000..39f7ce5 --- /dev/null +++ b/Writerside/cfg/buildprofiles.xml @@ -0,0 +1,22 @@ + + + + + + + + false + 2000 + favicon.ico + logo.svg + + Get MediaManager + https://github.com/maxdorninger/MediaManager/releases + true + https://github.com/maxdorninger/MediaManager + + + + + diff --git a/Writerside/images/favicon.ico b/Writerside/images/favicon.ico new file mode 100644 index 0000000..da80fad Binary files /dev/null and b/Writerside/images/favicon.ico differ diff --git a/Writerside/images/logo.svg b/Writerside/images/logo.svg new file mode 100644 index 0000000..b551d03 --- /dev/null +++ b/Writerside/images/logo.svg @@ -0,0 +1,158 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/Writerside/mm.tree b/Writerside/mm.tree new file mode 100644 index 0000000..6a06360 --- /dev/null +++ b/Writerside/mm.tree @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/Writerside/redirection-rules.xml b/Writerside/redirection-rules.xml new file mode 100644 index 0000000..ce11b76 --- /dev/null +++ b/Writerside/redirection-rules.xml @@ -0,0 +1,25 @@ + + + + + + Created after removal of "Installation" from MediaManager + installation.html + + + Created after removal of "About MediaManager" from MediaManager + starter-topic.html + + + Created after removal of "User Guide" from MediaManager + user-guide.html + + + Created after removal of "Quick Start Guide" from MediaManager + Quick-Start-Guide.html + + \ No newline at end of file diff --git a/Writerside/topics/Configuration.md b/Writerside/topics/Configuration.md new file mode 100644 index 0000000..21b1192 --- /dev/null +++ b/Writerside/topics/Configuration.md @@ -0,0 +1,6 @@ +# Configuration + +The configuration of MediaManager is divided into backend and frontend settings, which can be set in your +`docker-compose.yml` file or in separate `.env` files. +All settings are set as environment variables, because this makes backing up the configuration easier and allows for +easier sharing/transferring of the configuration. \ No newline at end of file diff --git a/Writerside/topics/Indexer-Settings.md b/Writerside/topics/Indexer-Settings.md new file mode 100644 index 0000000..5a61923 --- /dev/null +++ b/Writerside/topics/Indexer-Settings.md @@ -0,0 +1,9 @@ +# Indexer Settings + +## Prowlarr + +| Variable | Description | Default | Example | Required (if Prowlarr enabled) | +|--------------------|-------------------------------------|-------------------------|------------------------|--------------------------------| +| `PROWLARR_ENABLED` | Set to `True` to enable Prowlarr. | `True` | `true` | No | +| `PROWLARR_API_KEY` | Your Prowlarr API key. | - | `prowlarr_api_key` | Yes | +| `PROWLARR_URL` | Base URL of your Prowlarr instance. | `http://localhost:9696` | `http://prowlarr:9696` | No | diff --git a/Writerside/topics/api-reference.md b/Writerside/topics/api-reference.md new file mode 100644 index 0000000..2165507 --- /dev/null +++ b/Writerside/topics/api-reference.md @@ -0,0 +1,8 @@ +# API Reference + +Media Manager's backend is built with FastAPI, which automatically generates interactive API documentation. + +* **Swagger UI** (typically available at `http://localhost:8000/docs`). +* **ReDoc** (typically available at `http://localhost:8000/redoc`). + + diff --git a/Writerside/topics/authentication-setup.md b/Writerside/topics/authentication-setup.md new file mode 100644 index 0000000..0e40c65 --- /dev/null +++ b/Writerside/topics/authentication-setup.md @@ -0,0 +1,46 @@ +# Authentication + +MediaManager supports multiple authentication methods. Email/password authentication is the default, but you can also +enable OpenID Connect (OAuth 2.0) for integration with external identity providers. + + + + Note the lack of a trailing slash in some env vars like FRONTEND_URL. This is important. + + +| Variable | Description | Default | Example | Required | +|-------------------------|--------------------------------------------------------------------------|-----------------|-------------------------------------------|----------| +| `AUTH_TOKEN_SECRET` | Strong secret key for signing JWTs (create with `openssl rand -hex 32`). | - | `AUTH_TOKEN_SECRET=your_super_secret_key` | Yes | +| `AUTH_SESSION_LIFETIME` | Lifetime of user sessions in seconds. | `86400` (1 day) | `AUTH_SESSION_LIFETIME=604800` (1 week) | No | +| `AUTH_ADMIN_EMAIL` | Email address of the administrator accounts. | - | `AUTH_ADMIN_EMAIL=admin@example.com` | Yes | +| `FRONTEND_URL` | The url the frontend will be accessed from. | - | `https://mediamanager.example` | Yes | + + +On login/registration, every user whose email is in `AUTH_ADMIN_EMAIL` will be granted admin privileges. +Users whose email is not in `AUTH_ADMIN_EMAIL` will be regular users and will need to be verified by an administrator, +this can be done in the settings page. + +## OpenID Connect (OAuth 2.0) + +| Variable | Description | Default | Example | +|---------------------------------|--------------------------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------------------| +| `OPENID_ENABLED` | Enables OpenID authentication | `FALSE` | `TRUE` | +| `OPENID_CLIENT_ID` | Client ID from your OpenID provider. | - | - | +| `OPENID_CLIENT_SECRET` | Client Secret from your OpenID provider. | - | - | +| `OPENID_CONFIGURATION_ENDPOINT` | URL of your OpenID provider's discovery document (e.g., `.../.well-known/openid-configuration`). | - | `https://authentik.example.com/application/o/mediamanager/.well-known/openid-configuration` | +| `OPENID_NAME` | Display name for this OpenID provider. | `OpenID` | `Authentik` | + +### Configuring OpenID Connect + +1. Set `OPENID_ENABLED=TRUE` +2. Configure the following environment variables: + * `OPENID_CLIENT_ID` + * `OPENID_CLIENT_SECRET` + * `OPENID_CONFIGURATION_ENDPOINT` + * `OPENID_NAME` (optional) + * `FRONTEND_URL` (it is important that this is set correctly, as it is used for the redirect URIs) +3. Your OpenID server will likely want a redirect URI. This URL will be like: + `{FRONTEND_URL}/api/v1/auth/cookie/{OPENID_NAME}/callback`. The exact path depends on the `OPENID_NAME`. + +4. Example URL: `https://mediamanager.example/api/v1/auth/cookie/Authentik/callback` + diff --git a/Writerside/topics/configuration-backend.md b/Writerside/topics/configuration-backend.md new file mode 100644 index 0000000..c925ebd --- /dev/null +++ b/Writerside/topics/configuration-backend.md @@ -0,0 +1,65 @@ +# Backend + +These variables configure the core backend application, database connections, authentication, and integrations. They are +typically set as environment variables for the backend Docker container. + +## Database Settings + +| Variable | Description | Default | Example | +|---------------|------------------------------------------|----------------|--------------| +| `DB_HOST` | Hostname or IP of the PostgreSQL server. | `localhost` | `postgres` | +| `DB_PORT` | Port number of the PostgreSQL server. | `5432` | `5432` | +| `DB_USER` | Username for PostgreSQL connection. | `MediaManager` | `myuser` | +| `DB_PASSWORD` | Password for the PostgreSQL user. | `MediaManager` | `mypassword` | +| `DB_DBNAME` | Name of the PostgreSQL database. | `MediaManager` | `mydatabase` | + +## Metadata Provider Settings + +These settings configure the integrations with external metadata providers like The Movie Database (TMDB) and The TVDB. + +### TMDB (The Movie Database) + +TMDB is the primary metadata provider for MediaManager. It provides detailed information about movies and TV shows. +Get an API key from [The Movie Database](https://www.themoviedb.org/settings/api) to use this provider. You can create +an account and generate a free API key in your account settings. + + + Other software like Jellyfin use TMDB as well, so there won't be any metadata discrepancies. + + +| Variable | Default | Example | +|----------------|---------|---------------------------------------| +| `TMDB_API_KEY` | None | `TMDB_API_KEY=your_tmdb_api_key_here` | + +### TVDB (The TVDB) + + + The TVDB might provide false metadata, also it doesn't support some features of MediaManager like to show overviews, therfore TMDB is the preferred metadata provider. + + +Get an API key from [The TVDB](https://thetvdb.com/auth/register) to use this provider. You can create an account and +generate a free API key in your account settings. + +| Variable | Default | Example | +|----------------|---------|---------------------------------------| +| `TVDB_API_KEY` | None | `TVDB_API_KEY=your_tvdb_api_key_here` | + +## Directory Settings + + + Normally you don't need to change these, as the default mountpoints are usually sufficient. In your `docker-compose.yml`, you can just mount `/any/directory` to `/data/torrents`. + + +| Variable | Description | Default | +|---------------------|---------------------------------------------------|------------------| +| `IMAGE_DIRECTORY` | media images (posters, backdrops) will be stored. | `/data/images` | +| `TV_DIRECTORY` | location of TV show files | `/data/tv` | +| `MOVIE_DIRECTORY` | location of movie files | `/data/movies` | +| `TORRENT_DIRECTORY` | location of torrent files and downloads | `/data/torrents` | + +## Build Arguments (Dockerfile) + +| Argument | Description | Example (in build command) | +|-----------|--------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| +| `VERSION` | Labels the Docker image with a version. Passed during build (e.g., by GitHub Actions). Frontend uses this as `PUBLIC_VERSION`. | `docker build --build-arg VERSION=1.2.3 .` | + diff --git a/Writerside/topics/configuration-frontend.md b/Writerside/topics/configuration-frontend.md new file mode 100644 index 0000000..872cc1d --- /dev/null +++ b/Writerside/topics/configuration-frontend.md @@ -0,0 +1,14 @@ +# Frontend + +| Variable | Description | Default | Example | +|----------------------|----------------------------------------------------------------|--------------------------------|-------------------------------------------| +| `PUBLIC_WEB_SSR` | Enables/disables Server-Side Rendering. (this is experimental) | `false` | `true` | +| `PUBLIC_API_URL` | You (the browser) mut reach the backend from this url. | `http://localhost:8000/api/v1` | `https://mediamanager.example.com/api/v1` | +| `PUBLIC_SSR_API_URL` | The frontent container must reach the backend from this url. | `http://localhost:8000/api/v1` | `http://backend:8000/api/v1` | + +## Build Arguments (web/Dockerfile) + +| Argument | Description | Example (in build command) | +|-----------|-----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------| +| `VERSION` | Sets the `PUBLIC_VERSION` environment variable at runtime in the frontend container. Passed during build. | `docker build --build-arg VERSION=1.2.3 -f web/Dockerfile .` | + diff --git a/Writerside/topics/configuration-overview.md b/Writerside/topics/configuration-overview.md new file mode 100644 index 0000000..305b390 --- /dev/null +++ b/Writerside/topics/configuration-overview.md @@ -0,0 +1,34 @@ +# Installation Guide + +The recommended way to install and run Media Manager is using Docker and Docker Compose. + +1. **Prerequisites:** + * Ensure Docker and Docker Compose are installed on your system. + * If you plan to use OAuth 2.0 / OpenID Connect for authentication, you will need an account and client credentials + from an OpenID provider (e.g., Authentik, Pocket ID). + +2. **Setup:** + * Copy the docker-compose.yml from the MediaManager repo. + * Configure the necessary environment variables in your `docker-compose.yml` file. + * (Optional) Create a `.env` file in the root directory for backend environment variables and/or a `web/.env` for + frontend environment variables if you prefer to manage them separately from `docker-compose.yml`. + +3. **Running the Application:** + * Execute the command `docker-compose up -d` from the root directory. This will build the Docker images (if not + already built) and start all the services (backend, frontend, and potentially a database if configured in your + compose file). + * The backend will typically be available at `http://localhost:8000` and the frontend at `http://localhost:3000` (or + as configured). + +# Configuration Overview + +Media Manager is configured primarily through environment variables. These can be set in your `docker-compose.yml` file, +a `.env` file. + +Detailed configuration options are split into backend and frontend sections: + +* [Backend Configuration](configuration-backend.md) +* [Frontend Configuration](configuration-frontend.md) + +Build arguments are also used during the Docker image build process, primarily for versioning. + diff --git a/Writerside/topics/contributing.md b/Writerside/topics/contributing.md new file mode 100644 index 0000000..4d218d9 --- /dev/null +++ b/Writerside/topics/contributing.md @@ -0,0 +1 @@ +# Contributing \ No newline at end of file diff --git a/Writerside/topics/developer-guide.md b/Writerside/topics/developer-guide.md new file mode 100644 index 0000000..698fd7f --- /dev/null +++ b/Writerside/topics/developer-guide.md @@ -0,0 +1,45 @@ +# Developer Guide + +This section is for those who want to contribute to Media Manager or understand its internals. + +### Source Code + +- `media_manager/`: Backend FastAPI application (Python) +- `web/`: Frontend SvelteKit application (TypeScript) + +### Backend Development + +- Uses `uv` for dependency management (see `pyproject.toml` and `uv.lock`) +- Follows standard FastAPI project structure +- Database migrations are handled by Alembic (`alembic.ini`, `alembic/` directory) + +### Frontend Development + +- Uses `npm` for package management (see `web/package.json`) +- SvelteKit with TypeScript + +### Contributing + +- Please refer to the project's GitHub repository for contribution guidelines (e.g., forking, branching, pull requests) +- Consider opening an issue to discuss significant changes before starting work + +## Tech Stack + +### Backend + +- **Framework:** Python with FastAPI +- **Database ORM:** SQLAlchemy +- **Database Migrations:** Alembic +- **Dependency Management:** uv + +### Frontend + +- **Framework:** SvelteKit +- **Language:** TypeScript +- **Styling:** Tailwind CSS +- **Components:** shadcn-svelte for UI components + +### Deployment & CI/CD + +- Docker & Docker Compose +- GitHub Actions \ No newline at end of file diff --git a/Writerside/topics/introduction.md b/Writerside/topics/introduction.md new file mode 100644 index 0000000..7c4733c --- /dev/null +++ b/Writerside/topics/introduction.md @@ -0,0 +1,24 @@ +# MediaManager + +## About MediaManager + +Media Manager is a comprehensive solution for organizing, discovering, and accessing your personal media library, +including TV shows and movies. It provides a modern web interface for easy management and integrates with various +services for metadata and torrents. + +## Core Features + +* **Media Organization:** Efficiently manage your TV shows and movies. Keep track of what you have, what you've watched, + and what you want to watch. +* **Torrent Integration:** Seamlessly search for and manage torrents for your media files. +* **Metadata Fetching:** Automatically enriches your media library with detailed information, posters, and artwork from + metadata providers like TMDB and TVDB. +* **User Authentication:** Secure access to your media library with a robust authentication system, supporting: + * Username/Password (JWT and cookie-based sessions). + * OAuth 2.0 / OpenID Connect for integration with external identity providers (e.g., Authentik). +* **Web Interface:** A user-friendly frontend built with SvelteKit for browsing and managing your media. +* **API-driven:** A powerful FastAPI backend provides a comprehensive API for all functionalities. +* **Dockerized Deployment:** Easy to deploy and manage using Docker and Docker Compose. + + + diff --git a/Writerside/topics/troubleshooting.md b/Writerside/topics/troubleshooting.md new file mode 100644 index 0000000..5e46b75 --- /dev/null +++ b/Writerside/topics/troubleshooting.md @@ -0,0 +1,30 @@ +# Troubleshooting + + + Note the lack of a trailing slash in some env vars like FRONTEND_URL. This is important. + + + + Always check the container logs for more specific error messages + + +## Authentication Issues + + * Double-check `AUTH_TOKEN_SECRET`. If it changes, existing sessions/tokens will be invalidated. + * For OpenID: + * Verify `OPENID_CLIENT_ID`, `OPENID_CLIENT_SECRET`, and `OPENID_CONFIGURATION_ENDPOINT` are correct. + * Ensure the `FRONTEND_URL` is accurate and that your OpenID provider has the correct redirect URI whitelisted ( + e.g., `http://your-frontend-url/api/v1/auth/cookie/Authentik/callback`). + * Check backend logs for errors from `httpx_oauth` or `fastapi-users`. + +## CORS Errors + + * Ensure `FRONTEND_URL` is correctly set. + * Ensure your frontend's url is listed in `CORS_URLS`. + +## Data Not Appearing / File Issues + + * Verify that the volume mounts for `IMAGE_DIRECTORY`, `TV_DIRECTORY`, `MOVIE_DIRECTORY`, and `TORRENT_DIRECTORY` in + your `docker-compose.yml` are correctly pointing to your media folders on the host machine. + * Check file and directory permissions for the user running the Docker container (or the `node` user inside the + containers). diff --git a/Writerside/v.list b/Writerside/v.list new file mode 100644 index 0000000..2d12cb3 --- /dev/null +++ b/Writerside/v.list @@ -0,0 +1,5 @@ + + + + + diff --git a/Writerside/writerside.cfg b/Writerside/writerside.cfg new file mode 100644 index 0000000..baed983 --- /dev/null +++ b/Writerside/writerside.cfg @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file