GitHub - WallWhaleOrg/WallWhale: WallpaperEngineDownloader made with DepotDownloaderMod

WallWhale is a server and cli-tool for downloading and hosting Steam Built with TypeScript, Fastify, and Prisma, it provides secure API access, multi-account Steam integration, audit logging, and comprehensive monitoring. The system supports bulk downloads, automated deployments, and scales horizontally with Docker.

Important Notices

Warning

Docker Support Status: Experimental

The current Docker implementation is in experimental status. While Docker is supported as a deployment target, functionality has not been fully validated in all environments. Production use is not recommended at this time as it may result in container instability or data integrity issues.

Note

Development Status: Active

This project is under active development with an evolving API surface. Core functionality and interfaces may undergo significant changes without prior notification. Please consider this when implementing integration solutions.

Important

Legal Information

No Official Affiliation: WallWhale is an independent project with no affiliation, endorsement, or official connection to Valve Corporation or Steam.
Supported Content: This tool is specifically optimized for Wallpaper Engine content. While adaptable for other purposes with minor changes, no additional content types are officially supported.
Compliance Requirements: In accordance with the Steam Subscriber Agreement, WallWhale requires valid credentials and will only download content legitimately owned by or accessible to the provided account. The tool respects and enforces all ownership verification.
User Responsibility: Users bear sole responsibility for ensuring their legal right to use provided credentials. Project maintainers do not verify credential ownership and assume no liability for credential misuse.

Get started in 60 seconds:

# Docker (recommended)
docker-compose up -d
curl http://localhost:3000/health

# Local development
git clone https://github.com/MIKTHATGUY/WallWhale/ && cd WallWhale&& npm install && npm run db:push && npm run setup && npm run dev

Core components

API Server (src/index.ts, src/routes/) - Fastify web server with authentication, rate limiting, and OpenAPI documentation. Handles download requests, user management, and real-time monitoring endpoints.

Download Engine (src/services/downloadService.ts, src/utils/depotDownloader.ts) - Orchestrates Steam Workshop downloads using the DepotDownloader binary. Manages concurrent downloads, queue processing, and retry logic.

Database Layer (prisma/schema.prisma, src/plugins/prisma.ts) - Prisma ORM with SQLite/PostgreSQL support. Stores user accounts, download history, audit logs, and system configuration.

Authentication System (src/plugins/auth.ts, src/utils/crypto.ts) - Dual authentication with JWT tokens and API keys. Supports role-based access control and session management.

CLI Tools (src/commands/, src/utils/) - Command-line interface for server setup, certificate management, direct downloads, and maintenance operations.

File Hosting (src/utils/fileHosting.ts, src/utils/directDownload.ts) - Static file server with password protection, download tracking, and bandwidth limiting for serving downloaded workshop content.

Monitoring & Logging (src/plugins/audit.ts, src/utils/audit.ts) - Comprehensive audit logging, Prometheus metrics, health checks, and structured JSON logging for production observability.

Security Layer (src/utils/certificates.ts, src/plugins/register.ts) - TLS certificate management, input validation, CORS configuration, and secure headers for production deployments.

API workflow

Download a workshop item:

curl -X POST http://localhost:3000/v1/downloads \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"workshopId": "123456789", "steamAccount": "account_name"}'

Monitor progress:

curl http://localhost:3000/v1/downloads/download-id \
  -H "Authorization: Bearer your-api-key"

Production deployment

Docker Compose with external database:

# Set environment variables
export DATABASE_URL="postgresql://user:pass@host:5432/wallwhale"
export JWT_SECRET="your-jwt-secret"

# Deploy
docker-compose -f docker-compose.prod.yml up -d

# Verify deployment
curl https://your-domain.com/health

How to contribute

Fork the repo and create a branch for your change.
Install and run the app locally:

copy .env.example .env
npm install
npm run dev

Run tests and linters before submitting a PR:

npm run test
npm run lint

Open a PR describing the change and linking related issues.

See docs/CONTRIBUTING.md for detailed guidelines.

Support

Issues: https://github.com/MIKTHATGUY/WallWhale/issues
Docs: docs/ folder in this repository

Acknowledgements

Built for the Steam Workshop community. Thanks to contributors listed on the GitHub contributors tab.

If anything is unclear, open an issue and we’ll help you get started.

🔐 Enterprise Security - JWT authentication, API keys, role-based access, audit logging
⚡ High Performance - Concurrent downloads, intelligent queuing, rate limiting
🏗️ Production Ready - Docker support, health checks, monitoring, auto-scaling
🎮 Steam Integration - Multi-account support, workshop downloads, automated authentication
📊 Monitoring - Prometheus metrics, structured logging, real-time health checks
🔧 Developer Friendly - TypeScript, comprehensive testing, modular architecture

🚀 Quick Start

Docker (Recommended)

# Clone the repository
git clone https://github.com/wallwhale/wallwhale.git
cd wallwhale

# Start with Docker Compose
docker-compose up -d

# Check health
curl https://localhost:3000/health

Local Development

# Install dependencies
npm install

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

# Initialize database
npm run db:generate
npm run db:push
npm run db:seed

# Generate certificates (development)
npm run cert:mkcert

# Start development server
npm run dev

🏗️ Architecture

Enterprise-grade microservice architecture:

API Server - Fastify-based REST API with OpenAPI documentation
Download Engine - Multi-threaded WallWhale integration
Database Layer - Prisma ORM with PostgreSQL/SQLite support
Authentication - JWT + API key dual authentication system
Monitoring - Prometheus metrics, structured logging, health checks
Security - TLS encryption, rate limiting, audit trails

📚 Documentation

Core Documentation

Configuration: Environment variables, database setup, TLS certificates
API Usage: Authentication, endpoints, rate limiting, error handling
Security: Encryption, network security, audit logging, best practices
Operations: Deployment, monitoring, scaling, maintenance
Development: Local setup, testing, code standards, workflows

🔧 CLI Tools

Comprehensive command-line interface for server management:

# Certificate management
npm run cert:setup              # Interactive certificate wizard
npm run cert:mkcert            # Generate trusted dev certificates
npm run cert:letsencrypt       # Production Let's Encrypt certificates

# Direct downloads (no server required)
npm run cli download direct -i "123456789" -a "steam_account"

# File hosting and sharing
npm run cli download host -i "123456789" -p 8080 --password "secret"

# Server management
npm run health                 # Health check
npm run config:validate        # Validate configuration
npm run db:migrate            # Database migrations

🛠️ API Usage

Authentication

# Using API Key
curl -H "Authorization: Bearer your-api-key" \
     https://localhost:3000/v1/downloads

# Using JWT Token
curl -H "Authorization: Bearer jwt-token" \
     https://localhost:3000/v1/downloads

Download Workshop Item

curl -X POST https://localhost:3000/v1/downloads \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "workshopId": "123456789",
    "steamAccount": "your_steam_account"
  }'

Monitor Download

# Get download status
curl https://localhost:3000/v1/downloads/download-id \
  -H "Authorization: Bearer your-api-key"

# Stream real-time logs
curl https://localhost:3000/v1/downloads/download-id/logs \
  -H "Authorization: Bearer your-api-key" \
  -H "Accept: text/event-stream"

🔐 Security Features

Multi-Layer Authentication - JWT tokens + API keys with scope-based permissions
TLS Encryption - End-to-end encryption with Let's Encrypt integration
Rate Limiting - Configurable per-user and global rate limits
Audit Logging - Comprehensive audit trail for all operations
Input Validation - Strict input validation and sanitization
Network Security - CORS configuration, secure headers, IP whitelisting

📊 Monitoring & Operations

Health Checks - /health endpoint with detailed system status
Metrics - Prometheus metrics for performance monitoring
Logging - Structured JSON logging with configurable levels
Auto-Scaling - Docker Compose and Kubernetes support
Backup - Automated database and configuration backups

🌐 Deployment Options

Docker Compose (Production)

# Production deployment
docker-compose -f docker-compose.prod.yml up -d

# With external database
docker-compose -f docker-compose.external-db.yml up -d

Kubernetes

# Deploy to Kubernetes
kubectl apply -f k8s/

# Scale deployment
kubectl scale deployment wallwhale-server --replicas=3

Traditional Server

# Production build
npm run build

# Start production server
npm run start:prod

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

Development Setup - Local environment configuration
Coding Standards - TypeScript style guide and best practices
Testing Guidelines - Unit, integration, and e2e testing
Pull Request Process - Code review and merge workflow

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Documentation: Check the /docs directory for comprehensive guides
Issues: Report bugs and request features on GitHub Issues
Discussions: Ask questions in GitHub Discussions
Troubleshooting: See Troubleshooting Guide for common issues

🏆 Enterprise Ready

WallWhale is designed for enterprise environments with:

High Availability - Multi-instance deployment with load balancing
Scalability - Horizontal scaling with Docker and Kubernetes
Security - Enterprise-grade security features and audit compliance
Monitoring - Production-ready observability and alerting
Support - ~~Comprehensive documentation~~ and community support

Built with ❤️ for the WallpaperEngine community

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github/workflows		.github/workflows
docs		docs
prisma		prisma
scripts		scripts
src		src
test		test
.env.example		.env.example
.enver		.enver
.prettierrc.json		.prettierrc.json
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SETUP.md		SETUP.md
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.prod.json		tsconfig.prod.json
vitest.config.ts		vitest.config.ts

License

WallWhaleOrg/WallWhale

Folders and files

Latest commit

History

Repository files navigation

Important Notices

Core components

API workflow

Production deployment

How to contribute

Docs & quick links

Support

Acknowledgements

🚀 Quick Start

Docker (Recommended)

Local Development

🏗️ Architecture

📚 Documentation

Quick Links

Core Documentation

🔧 CLI Tools

🛠️ API Usage

Authentication

Download Workshop Item

Monitor Download

🔐 Security Features

📊 Monitoring & Operations

🌐 Deployment Options

Docker Compose (Production)

Kubernetes

Traditional Server

🤝 Contributing

📝 License

🆘 Support

🏆 Enterprise Ready

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages