ALPHA VERSION -- DVD Database Server - SHA1-based Content Lookup API

🚀 Quick Start

Install DVD Database Server on Ubuntu/Debian with a single command:

bash <(curl -fsSL https://projects.thedude.vip/dvddb/install.sh)

The installer will:

Add the Silver Linings apt repository
Install dvddb-server and Perl dependencies
Configure PostgreSQL database connection
Generate application secrets
Install and start the systemd service
Verify the health endpoint is responding

✨ Features

🔍 SHA1 Lookups

Fast O(1) content lookups using SHA1 hashes of DVD titles with three response types.

🔐 Token Authentication

Secure Bearer token authentication with SHA256 hashing. Tokens never stored in plaintext.

⚖️ Point System

Token bucket throttling with configurable limits per API key. Fair resource allocation.

📊 Three Response Types

exists (1pt), skel (10pts), full (50pts) - pay for what you need. Optimized for efficiency.

🐘 PostgreSQL

Optimized schema with JSONB, ENUMs, and indexes. Supports concurrent requests.

🔄 Zero Downtime

Hot reloads with Hypnotoad for seamless updates without dropping connections.

🏗️ Architecture

Internet (HTTPS)
    ↓
Nginx Reverse Proxy (SSL termination)
    ↓
Mojolicious/Hypnotoad (API server :8080)
    ↓
PostgreSQL 16+ (content + auth + throttling)

Components

Mojolicious: Modern Perl web framework with non-blocking I/O
Hypnotoad: Production-ready prefork server with zero-downtime reloads
Mojo::Pg: Non-blocking PostgreSQL driver with connection pooling
PostgreSQL 16+: Database with JSONB support and optimized indexes
Nginx: Reverse proxy with SSL/TLS termination and rate limiting

Network Topology

10.10.0.x: Data/API network (PostgreSQL, API traffic)
10.20.0.x: Admin/SSH network (management access only)
Public: HTTPS access via api.dvddb.org

📦 Manual Installation

For those who prefer step-by-step installation:

1. Add Repository and Install Package

# Add GPG key curl -fsSL https://projects.thedude.vip/apt/silver-linings.gpg.key | \ sudo gpg --dearmor -o /etc/apt/keyrings/silver-linings.gpg # Add repository echo "deb [signed-by=/etc/apt/keyrings/silver-linings.gpg] https://projects.thedude.vip/apt ./" | \ sudo tee /etc/apt/sources.list.d/silver-linings.list # Install sudo apt update sudo apt install dvddb-server

2. Configure Database Connection

Create /opt/dvddb-api/config/dvddb_api.production.conf:

{ secrets => ['YOUR_RANDOM_SECRET_HERE'], database => { dsn => 'dbi:Pg:dbname=dvddb;host=10.10.0.116;port=5432', username => 'dvddb_api', password => 'YOUR_PASSWORD_HERE', options => { AutoCommit => 1, RaiseError => 1, PrintError => 0, pg_enable_utf8 => 1, } }, hypnotoad => { listen => ['http://127.0.0.1:8080'], workers => 4, }, point_costs => { exists => 1, skel => 10, full => 50, }, log => { level => 'info', path => 'log/dvddb_api.log', }, }

3. Apply Database Schema

psql -h 10.10.0.116 -U dvddb_api -d dvddb \ -f /usr/share/doc/dvddb-server/schema.sql

4. Install and Start Service

sudo cp /opt/dvddb-api/deployment/systemd/dvddb-server.service \ /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable dvddb-server sudo systemctl start dvddb-server

5. Verify Installation

# Check service status sudo systemctl status dvddb-server # Test health endpoint curl http://localhost:8080/health # View logs sudo journalctl -u dvddb-server -f

🔑 API Token Management

Generate tokens for API access:

export DVDDB_PG_PASSWORD='your_db_password' cd /opt/dvddb-api ./scripts/generate_token.sh "Token Name" "Description" 5000 10 # Arguments: # "Token Name" - Friendly name for the token # "Description" - Purpose/owner information # 5000 - Max points (bucket size) # 10 - Points per minute (regen rate)

The script will output a token hash. Use this in API requests:

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \ https://api.dvddb.org/api/v1/lookup/SHA1_HASH?type=exists

🆘 Support

Documentation

API Reference - Complete endpoint documentation
Changelog - Version history and known issues
Silver Linings Projects

Useful Commands

# Service management sudo systemctl status dvddb-server sudo systemctl restart dvddb-server sudo systemctl reload dvddb-server # Zero-downtime # Logs sudo journalctl -u dvddb-server -f tail -f /opt/dvddb-api/log/dvddb_api.log # Health check curl http://localhost:8080/health # Test API (requires token) TOKEN="your_token_here" curl -H "Authorization: Bearer $TOKEN" \ "http://localhost:8080/api/v1/lookup/0000000000000000000000000000000000000000?type=exists"

Troubleshooting

Service won't start: Check logs with journalctl -u dvddb-server -n 50
Database connection failed: Verify pg_hba.conf allows connections from API server
Port 8080 in use: Check for conflicting services with ss -tlnp | grep 8080
Permission denied: Ensure config file is owned by gardner:gardner with 600 permissions

🔒 Security Considerations

⚠️ Alpha Software Warning: This is alpha-quality software with known major bugs. Do not use in production without thorough testing.

Tokens stored as SHA256 hashes only (never plaintext)
PostgreSQL access restricted to 10.10.0.* network
SSL/TLS enforced for all external API communication
Point-based throttling prevents abuse
Firewall (nftables) restricts access to authorized IPs only
Configuration files with secrets NOT in git (*.production.conf)
File permissions: 600 on config files with secrets