benbou/mediavault repository overview

⁠MediaVault

MediaVault is a lightweight, self-hosted movie and TV library manager built with Streamlit.

It provides a simple browser-based interface for maintaining a personal media catalog, optionally enriching entries with metadata from TMDB.

The application stores its library in plain CSV files, making the data easy to inspect, back up, migrate, or edit outside the application.

The Docker image is designed for simple self-hosting and includes support for unRAID-style PUID / PGID ownership.

⁠Features

• Manage separate Movies and TV Shows libraries
• Search TMDB for movie and television metadata
• Optional TMDB integration — MediaVault works without an API key
• Automatic duplicate detection using:
  • TMDB ID
  • normalized title and year
• Track fields such as:
  • watched
  • owned
  • can't find
  • notes
• Persistent CSV-based storage
• Browser-based Streamlit interface
• Built-in container health check
• Runs the application as a non-root user
• Read-only application filesystem support
• unRAID-friendly PUID / PGID configuration
• Multi-stage Docker image keeping development/test tooling out of the runtime image

⁠Quick Start

Create a directory for persistent data:

mkdir -p data

Run MediaVault:

docker run -d \
  --name mediavault \
  --restart unless-stopped \
  -p 8501:8501 \
  -e PUID=99 \
  -e PGID=100 \
  -e TMDB_API_KEY= \
  -v "$(pwd)/data:/app/data" \
  --read-only \
  --tmpfs /tmp:size=64m,mode=1777 \
  --security-opt no-new-privileges:true \
  benbou/mediavault:latest

Open:

http://YOUR_SERVER_IP:8501

Your library data is stored outside the container in the mounted data directory.

⁠Docker Compose

Example compose.yaml:

services:
  mediavault:
    image: benbou/mediavault:latest
    container_name: mediavault

    ports:
      - "8501:8501"

    environment:
      PUID: "99"
      PGID: "100"
      TMDB_API_KEY: ""

    volumes:
      - ./data:/app/data

    read_only: true

    tmpfs:
      - /tmp:size=64m,mode=1777

    security_opt:
      - no-new-privileges:true

    restart: unless-stopped

Start it with:

docker compose up -d

⁠TMDB Metadata

TMDB integration is optional.

Without an API key, MediaVault can still be used as a normal manually maintained media library.

To enable TMDB search and metadata retrieval, obtain a TMDB API key and provide it using:

TMDB_API_KEY=your_api_key

For example:

-e TMDB_API_KEY=your_api_key

or in Compose:

environment:
  TMDB_API_KEY: "your_api_key"

⁠Persistent Storage

MediaVault stores its library under:

/app/data

The directory contains CSV files such as:

movies.csv
tv_shows.csv

Mount /app/data to persistent storage on the host.

Example:

-v /path/to/mediavault/data:/app/data

Because the application uses standard CSV files, your library remains accessible independently of the Docker container.

⁠Image Tags

MediaVault images use three types of tags.

⁠latest

benbou/mediavault:latest

Tracks the newest stable MediaVault Docker release.

This is the simplest tag for normal installations.

⁠Version tags

Example:

benbou/mediavault:1.3.12

Version tags correspond to specific MediaVault releases.

For deployments where predictable upgrades are preferred, pinning a version is recommended:

image: benbou/mediavault:1.3.12

⁠Commit tags

Example:

benbou/mediavault:sha-012345abcdef

Commit tags identify the exact source revision associated with a published build.

They are useful for diagnostics, testing, or explicitly selecting a particular build.

⁠Prereleases

Prerelease versions may be published using tags such as:

1.4.0-rc.1
1.4.0-beta.1

Prerelease images do not update the stable latest tag.

⁠unRAID

MediaVault is designed to work well with unRAID.

Suggested Docker template settings:

Use the data mapping as Read/Write.

Example:

/mnt/user/appdata/mediavault/data
        ↓
/app/data

The default:

PUID=99
PGID=100

matches the commonly used unRAID nobody:users identity.

Do not configure an additional Docker-level container user.

The MediaVault entrypoint starts with the permissions required to prepare /app/data, then drops privileges before starting the application.

⁠Architecture

MediaVault has a deliberately simple architecture:

Browser
   │
   ▼
Streamlit Web Application
   │
   ├── Movie Library
   ├── TV Library
   └── TMDB API (optional)
   │
   ▼
/app/data
   ├── movies.csv
   └── tv_shows.csv

There is no external database server.

Persistent application state is stored in CSV files mounted into /app/data.

This keeps deployment, backups, and migration straightforward.

⁠Health Check

The image includes a Docker health check against Streamlit's internal health endpoint:

http://127.0.0.1:8501/_stcore/health

The health check uses Python's standard library from inside the container and does not require curl.

You can inspect the status with:

docker inspect \
  --format='{{.State.Health.Status}}' \
  mediavault

Typical states are:

starting
healthy
unhealthy

⁠Security

The published image is designed to run with a restricted runtime configuration.

⁠Non-root application process

The container starts only long enough to prepare the persistent data directory and then launches MediaVault using the configured numeric:

PUID
PGID

The Streamlit application itself does not run as root.

⁠Read-only application filesystem

Recommended deployment uses:

--read-only

The application files therefore cannot normally be modified at runtime.

Persistent writes are limited to the mounted:

/app/data

directory.

⁠Temporary filesystem

A small temporary filesystem is mounted at:

/tmp

Example:

--tmpfs /tmp:size=64m,mode=1777

⁠Privilege escalation protection

Recommended deployments use:

--security-opt no-new-privileges:true

This prevents processes inside the container from acquiring additional privileges.

⁠Minimal runtime dependencies

Testing and linting packages are installed only in the Docker build/test stage and are not included as development tooling in the published runtime image.

⁠Environment Variables

* The supplied unRAID examples use 99:100.

For normal Docker deployments, /app/data should remain the application data directory because that is the expected persistent volume location.

⁠Ports

MediaVault listens on:

8501/tcp

Example host mapping:

8501:8501

The host-side port may be changed if necessary:

8080:8501

MediaVault would then be available at:

http://YOUR_SERVER_IP:8080

⁠Updating

When using latest:

docker pull benbou/mediavault:latest

Then recreate the container using your normal Docker or Compose workflow.

Your movie and TV library remain persistent as long as /app/data remains mapped to the same host directory.

For deployments where upgrades should be explicitly controlled, use a version tag instead:

benbou/mediavault:1.3.12

⁠Backup

Backing up MediaVault is straightforward.

Back up the host directory mapped to:

/app/data

For example, on unRAID:

/mnt/user/appdata/mediavault/data

The important files are the CSV library files contained in that directory.

No separate database dump is required.

⁠License

MIT