DeckVault

Open-source, self-hosted game library tracker for Steam Deck and other storage devices.

---

DeckVault tracks which games are installed across your internal storage, SD cards, HDDs, and SSDs — all from a single dashboard. It integrates with IGDB for cover art and metadata, detects duplicates across devices, and ships as a single Docker container with no external dependencies.

Table of Contents

• Features
• Screenshots
• Getting Started
  • Docker Compose
  • Docker Run
  • First Setup
  • Updating
• Configuration
• IGDB Setup
• Data
• Development
• Contributors
• License

Features

• Storage dashboard: Overview of all your storage devices with usage stats at a glance.
• Per-device game lists: See exactly which games are on each SD card, HDD, SSD, or internal drive.
• IGDB integration: Search IGDB to add games with cover art and metadata automatically.
• Library view: All games across all devices in one place, with duplicate detection highlighted.
• Multiple device types: Supports internal storage, SD cards, HDDs, and SSDs with color-coding.
• Dark/light theme: Follows your system preference with a manual override.
• PWA-ready: Install DeckVault on any device — desktop, Android, or iOS — for a native app feel.
• JWT authentication: Secure session cookies, no third-party auth required.
• Single container: Frontend and backend ship together — no separate services to manage.

Screenshots

See more screenshots

Library

Storage

Getting Started

Prerequisites

• Docker and Docker Compose

Images are hosted on Docker Hub (bellamy/deckvault). A mirror is also available on GHCR (ghcr.io/ellite/deckvault) if you prefer.

Docker Compose

1. Download the compose file:

curl -o docker-compose.yml https://raw.githubusercontent.com/ellite/deckvault/main/docker-compose.yml

2. Generate a secret key and set it in docker-compose.yml:

# Python
python3 -c "import secrets; print(secrets.token_hex(32))"

# OpenSSL
openssl rand -hex 32

services:
  deckvault:
    image: ghcr.io/ellite/deckvault:latest
    container_name: deckvault
    restart: unless-stopped
    ports:
      - "4367:4367"
    environment:
      - PUID=1000
      - PGID=1000
      - SECRET_KEY=changeme   # ← generate with: openssl rand -hex 32
    volumes:
      - ./data:/app/backend/data

3. Start:

docker compose up -d

Docker Run

docker run -d \
  --name deckvault \
  --restart unless-stopped \
  -p 4367:4367 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e SECRET_KEY="$(openssl rand -hex 32)" \
  -v ./data:/app/backend/data \
  ghcr.io/ellite/deckvault:latest

First Setup

1. Open http://localhost:4367 in your browser.
2. Register an account — all data is local to your instance.
3. Add your first storage device and start tracking games.

Updating

docker compose pull && docker compose up -d

Database migrations run automatically on startup — no manual steps required.

Configuration

Variable	Default	Description
SECRET_KEY	-	Required. JWT signing key. Generate with openssl rand -hex 32.
PUID	1000	User ID to run the process as.
PGID	1000	Group ID to run the process as.
BACKEND_PORT	8000	Internal port the backend binds to. Override only if 8000 conflicts on bare metal.

IGDB Setup

IGDB provides cover art and game metadata. It's optional — you can add games manually without it.

1. Go to dev.twitch.tv and create an application.
2. Copy the Client ID and generate a Client Secret.
3. In DeckVault, go to Settings and enter your credentials.

Data

All data is stored in ./data/deckVault.db. Back this file up to preserve your library.

The data/ directory is a bind mount, so it persists across container rebuilds and restarts.

Port	Service
4367	DeckVault web UI

The backend API is internal-only and not exposed outside the container.

Development

View instructions

Requirements

• Python 3.12+
• Node.js 22+

Backend

cd backend
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000

Frontend

cd frontend
npm install
API_URL=http://localhost:8000 npm run dev

The frontend dev server starts on http://localhost:4367 and proxies API calls to the backend on port 8000.

Contributors

License

This project is licensed under the GNU General Public License, Version 3 - see the LICENSE.md file for details.