Documentation

Complete installation and setup guides to get DosVault running perfectly in any environment. From quick Docker setup to advanced configuration options.

Quick Start Guide

Get DosVault running in under 5 minutes

Get Your IGDB Credentials

DosVault uses the IGDB (Internet Game Database) to fetch game metadata. You'll need free Twitch Developer credentials to access their API.

Visit dev.twitch.tv/console
Create a new application
Set OAuth Redirect URL to http://localhost
Copy your Client ID and Client Secret

Run with Docker (Recommended)

The easiest way to run DosVault is with Docker. Create your ROM directory and start the container with your configuration as environment variables.

# Create directories
mkdir -p ~/dosvault/roms

# Run DosVault with environment variables
docker run -d \
  --name dosvault \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 8081:8081 \
  -v dosvault-data:/app/data \
  -v ~/dosvault/roms:/app/data/roms:ro \
  -e DOSVAULT_ADMIN_USERNAME=admin \
  -e [email protected] \
  -e DOSVAULT_ADMIN_PASSWORD=your_secure_password \
  -e IGDB_CLIENT_ID=your_twitch_client_id \
  -e IGDB_SECRET_KEY=your_twitch_secret_key \
  -e DOSFRONTEND_CONFIG_DIR=/app/data \
  tty303/dosvault:latest

Access Your Library

Open your browser to http://localhost:8080, create your admin account, and start scanning your ROM collection!

Installation Methods

Choose the installation method that works best for you

Docker Installation

Recommended for most users

# Using docker run
docker run -d \
  --name dosvault \
  -p 8080:8080 \
  -p 8081:8081 \
  -v dosvault-data:/app/data \
  -v /path/to/roms:/app/data/roms:ro \
  -e DOSVAULT_ADMIN_USERNAME=admin \
  -e [email protected] \
  -e DOSVAULT_ADMIN_PASSWORD=your_password \
  -e IGDB_CLIENT_ID=your_client_id \
  -e IGDB_SECRET_KEY=your_secret_key \
  tty303/dosvault:latest

# Using docker-compose
services:
  dosvault:
    image: tty303/dosvault:latest
    ports:
      - "${DOSVAULT_PORT:-8080}:8080"
      - "${DOSVAULT_WEBSOCKET_PORT:-8081}:8081"
    volumes:
      - dosvault_data:/app/data
      - "${ROMS_PATH:-./roms}:/app/data/roms:ro"
    environment:
      - IGDB_CLIENT_ID=${IGDB_CLIENT_ID}
      - IGDB_SECRET_KEY=${IGDB_SECRET_KEY}
      - DOSFRONTEND_CONFIG_DIR=/app/data
      - DOSVAULT_ADMIN_USERNAME=${DOSVAULT_ADMIN_USERNAME:-}
      - DOSVAULT_ADMIN_EMAIL=${DOSVAULT_ADMIN_EMAIL:-}
      - DOSVAULT_ADMIN_PASSWORD=${DOSVAULT_ADMIN_PASSWORD:-}
    restart: unless-stopped

volumes:
  dosvault_data:
    driver: local

From Source

For developers and advanced users

# Clone repository
git clone https://github.com/th3r00t/dosvault.git
cd dosvault

# Install dependencies
pip install -r requirements.txt

# Set up environment
cp .env.example .env
# Edit .env with your credentials

# Initialize database
python -m dosvault db-init

# Run application
python -m dosvault serve

Configuration Reference

Complete list of configuration options

# Environment Variables / .env file

# Required: IGDB API Credentials
IGDB_CLIENT_ID=your_twitch_client_id       # Required
IGDB_SECRET_KEY=your_twitch_secret_key     # Required

# Paths
ROM_PATH=/path/to/your/roms                # Path to ROM directory
DATA_PATH=/path/to/data                    # Database and images storage
IMAGES_PATH=/path/to/images                # Game artwork storage
DATABASE_PATH=/path/to/database.db         # SQLite database file

# Web Server
HOST=0.0.0.0                              # Server bind address
PORT=8080                                 # Server port
WORKERS=1                                 # Number of worker processes

# Security
JWT_SECRET_KEY=your-secret-key            # JWT signing key (auto-generated if not set)
JWT_ALGORITHM=HS256                       # JWT algorithm
JWT_EXPIRE_MINUTES=1440                   # JWT token expiration (24 hours)

# Scanning
BATCH_SIZE=50                             # Database batch processing size
MAX_CONCURRENT_REQUESTS=4                 # API request concurrency limit
SCAN_RECURSIVE=true                       # Scan subdirectories recursively

# Logging
LOG_LEVEL=INFO                            # Logging level (DEBUG, INFO, WARNING, ERROR)
LOG_FORMAT=detailed                       # Log format (simple, detailed, json)

Advanced Docker Configuration

Production-ready Docker setups and best practices

Production Docker Compose

Complete docker-compose.yml for production deployments with health checks, logging, and restart policies.

services:
  dosvault:
    image: tty303/dosvault:latest
    container_name: dosvault
    restart: unless-stopped
    
    ports:
      - "${DOSVAULT_PORT:-8080}:8080"
      - "${DOSVAULT_WEBSOCKET_PORT:-8081}:8081"
    
    volumes:
      - dosvault_data:/app/data
      - "${ROMS_PATH:-./roms}:/app/data/roms:ro"
    
    environment:
      # IGDB API Configuration
      - IGDB_CLIENT_ID=${IGDB_CLIENT_ID}
      - IGDB_SECRET_KEY=${IGDB_SECRET_KEY}
      # Application Configuration  
      - DOSFRONTEND_CONFIG_DIR=/app/data
      - DOSVAULT_ADMIN_USERNAME=${DOSVAULT_ADMIN_USERNAME:-}
      - DOSVAULT_ADMIN_EMAIL=${DOSVAULT_ADMIN_EMAIL:-}
      - DOSVAULT_ADMIN_PASSWORD=${DOSVAULT_ADMIN_PASSWORD:-}
      # Additional Settings
      - LOG_LEVEL=INFO
      - WORKERS=2
    
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    
    # Security
    user: "1000:1000"
    read_only: true
    tmpfs:
      - /tmp:noexec,nosuid,size=100m
    
    # Resource limits
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '1.0'
        reservations:
          memory: 256M
          cpus: '0.25'

volumes:
  dosvault_data:
    driver: local

Security Best Practices

Recommended security configurations for production deployments.

# Use specific image tags, not 'latest'
image: dosvault/dosvault:v1.2.3

# Run as non-root user
user: "1000:1000"

# Mount ROM directory as read-only
- ./roms:/app/roms:ro

# Use Docker secrets for sensitive data
secrets:
  - igdb_client_id
  - igdb_secret_key

# Enable read-only root filesystem
read_only: true

# Create temporary filesystem for writable areas
tmpfs:
  - /tmp:noexec,nosuid,size=100m

Reverse Proxy Setup

Configure DosVault behind nginx or Traefik for SSL termination and domain access.

# Nginx configuration
server {
    listen 443 ssl http2;
    server_name dosvault.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# Traefik labels
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.dosvault.rule=Host(`dosvault.com`)"
  - "traefik.http.routers.dosvault.tls.certresolver=letsencrypt"

Database Management

Backup, migration, and maintenance commands

Database Commands

# Initialize new database
dosvault db-init

# Create admin user
dosvault create-admin

# Run migrations
dosvault migrate upgrade

# Create new migration
dosvault migrate create "description"

# Check migration status
dosvault migrate check

Backup & Restore

# Backup database
cp /path/to/data/dosvault.db backup.db

# Backup with Docker
docker exec dosvault cp /app/data/dosvault.db /tmp/
docker cp dosvault:/tmp/dosvault.db backup.db

# Restore database
cp backup.db /path/to/data/dosvault.db

# Restore with Docker
docker cp backup.db dosvault:/app/data/dosvault.db

Troubleshooting

Common issues and their solutions

IGDB API Issues

Problem: "IGDB authentication failed" or metadata not loading

Solution: Verify your Twitch credentials are correct and active:

# Test your credentials
curl -X POST 'https://id.twitch.tv/oauth2/token' \
  -d 'client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials'

Database Errors

Problem: Database locked or corruption errors

Solution: Stop DosVault, check database integrity, and restore from backup if needed:

# Check database integrity
sqlite3 dosvault.db "PRAGMA integrity_check;"

# Repair database (creates new file)
sqlite3 dosvault.db ".backup repair.db"

Permission Issues

Problem: Can't access ROM files or write to data directory

Solution: Fix file permissions and ownership:

# Fix ROM directory permissions
sudo chown -R 1000:1000 /path/to/roms
sudo chmod -R 755 /path/to/roms

# Fix data directory permissions
sudo chown -R 1000:1000 /path/to/data
sudo chmod -R 755 /path/to/data

Performance Issues

Problem: Slow scanning or high memory usage

Solutions:

Reduce BATCH_SIZE in configuration (default: 50)
Lower MAX_CONCURRENT_REQUESTS (default: 4)
Increase memory limits in Docker
Consider using SSD storage for database

API Reference

REST API endpoints for developers

Authentication

# Login
POST /api/auth/login
{
  "username": "admin",
  "password": "password"
}

# Response
{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "user": {...}
}

Games

# List games
GET /api/games?page=1&per_page=50

# Get game details
GET /api/games/{game_id}

# Mark favorite
POST /api/games/{game_id}/favorite

# Download game
GET /api/games/{game_id}/download

Admin

# Start ROM scan
POST /api/admin/rom-scan

# Get system stats
GET /api/admin/stats

# User management
GET /api/admin/users
POST /api/admin/users
PUT /api/admin/users/{user_id}

Search

# Search games
GET /api/games/search?q=doom

# Filter by genre
GET /api/games?genre=action

# Filter by year
GET /api/games?year=1993

Need More Help?

Our community is here to help with any questions or issues

Report Issues Community Discussions Contact Support