Skip to content
Klutch.sh Docs

Deploying Gaseous Server

Introduction

Gaseous Server is a self-hosted game ROM manager with a built-in web-based emulator that uses multiple sources to identify and provide metadata for your game collection. This platform transforms your scattered ROM files into an organized, browsable library with cover art, descriptions, and in-browser gameplay capabilities.

Built with .NET and featuring a modern web interface, Gaseous Server scans your ROM directories, identifies games using databases like IGDB (Internet Game Database), and presents them through a beautiful interface. The integrated EmulatorJS provides in-browser emulation for various retro gaming platforms.

Key highlights of Gaseous Server:

  • Automatic ROM Detection: Scans directories and identifies games using checksums and metadata databases
  • IGDB Integration: Fetches game artwork, descriptions, and metadata from the Internet Game Database
  • Web-Based Emulation: Play games directly in your browser with EmulatorJS integration
  • Multi-Platform Support: Supports ROMs from numerous retro gaming platforms
  • User Authentication: Secure access with user accounts and OIDC/OAuth2 support
  • Two-Factor Authentication: Enhanced security with 2FA for password-based logins
  • Collection Organization: Organize games by platform, genre, or custom collections
  • Cover Art Display: Beautiful grid view with game cover images
  • Open Source: Active development with community contributions

This guide walks through deploying Gaseous Server on Klutch.sh using Docker, configuring persistent storage for your ROM library, and setting up the application for production use.

Why Deploy Gaseous Server on Klutch.sh

Deploying Gaseous Server on Klutch.sh provides several advantages for managing your retro game library:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Gaseous Server without complex orchestration or manual server configuration. Push to GitHub, and your ROM manager deploys automatically.

Persistent Storage: Attach persistent volumes for your ROM library, database, and configuration. Your game collection and metadata survive container restarts and redeployments without data loss.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your game library from anywhere without manual certificate management.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your Dockerfile trigger automatic redeployments, keeping your deployment in sync with your repository.

Scalable Resources: Allocate CPU and memory based on your library size and emulation needs. Start small and scale up as your collection grows.

Environment Variable Management: Securely store sensitive configuration like IGDB API credentials through Klutch.sh’s environment variable system without exposing credentials in your repository.

Custom Domains: Assign a custom domain to your Gaseous Server instance for a professional gaming portal experience.

Always-On Availability: Your game library remains accessible 24/7 for browser-based gaming from any device.

Prerequisites

Before deploying Gaseous Server on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your Gaseous Server configuration
  • Basic familiarity with Docker and containerization concepts
  • An IGDB API key for metadata fetching (Twitch Developer account required)
  • Your ROM files ready to upload
  • (Optional) A custom domain for your Gaseous Server instance

Understanding Gaseous Server Architecture

Gaseous Server is built on a modern .NET stack designed for ROM management and emulation:

.NET Backend: The core application runs on .NET, providing robust ROM scanning, metadata management, and API functionality.

MariaDB/MySQL Database: Gaseous Server uses MariaDB for storing game metadata, user accounts, and library organization. The database maintains relationships between ROMs and their metadata.

EmulatorJS Integration: The built-in web emulator leverages EmulatorJS for browser-based gameplay, supporting multiple retro platforms without plugins.

IGDB Metadata Provider: Integration with the Internet Game Database provides artwork, descriptions, release dates, and other metadata for identified games.

File-Based ROM Storage: ROMs are stored on the filesystem and scanned by the application for identification and organization.

Preparing Your Repository

To deploy Gaseous Server on Klutch.sh, create a GitHub repository containing your Dockerfile and any custom configuration.

Repository Structure

gaseous-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository. This example uses the official Gaseous Server image:

FROM gaseousgames/gaseousserver:latest


# Set timezone
ENV TZ=${TZ:-UTC}


# Create directories for ROM storage
RUN mkdir -p /games /config


# Expose the web interface port
EXPOSE 5000


# The base image includes the default entrypoint

Advanced Dockerfile with Custom Configuration

For more control over your deployment, use this extended Dockerfile:

FROM gaseousgames/gaseousserver:latest


# Set timezone
ENV TZ=${TZ:-UTC}


# Create necessary directories
RUN mkdir -p /games /games/nes /games/snes /games/genesis /config /data


# Set proper permissions
RUN chmod -R 755 /games /config /data


# Health check to verify application is running
HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:5000 || exit 1


# Expose the application port
EXPOSE 5000

Creating the .dockerignore File

Create a .dockerignore file to exclude unnecessary files from the build:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
node_modules/
.env
.env.local

Environment Variables Reference

Gaseous Server requires several environment variables for proper operation:

VariableRequiredDefaultDescription
TZNoUTCContainer timezone
dbhostYes-MariaDB database host
dbuserYes-MariaDB username
dbpassYes-MariaDB password
dbnameYesgaseousMariaDB database name
igaboression_ClientIdYes-IGDB/Twitch Client ID
igaboression_ClientSecretYes-IGDB/Twitch Client Secret

Deploying Gaseous Server on Klutch.sh

Once your repository is prepared, follow these steps to deploy Gaseous Server:

    Obtain IGDB API Credentials

    Gaseous Server requires IGDB API access for metadata:

    1. Create a Twitch Developer account
    2. Register a new application
    3. Note your Client ID and generate a Client Secret
    4. These credentials provide access to the IGDB API

    Set Up MariaDB Database

    Gaseous Server requires MariaDB for data storage. Deploy a MariaDB instance on Klutch.sh or use an existing database. Create a database named gaseous for the application.

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

    Terminal window
    git init
    git add Dockerfile .dockerignore README.md
    git commit -m "Initial Gaseous Server deployment configuration"
    git remote add origin https://github.com/yourusername/gaseous-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “gaseous” or “retro-games”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Gaseous Server Dockerfile.

    Configure HTTP Traffic

    Gaseous Server serves its web interface over HTTP. In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 5000 (Gaseous Server’s default port)

    Set Environment Variables

    In the environment variables section, add the following:

    VariableValue
    TZYour timezone (e.g., America/New_York)
    dbhostYour MariaDB host
    dbuserYour MariaDB username
    dbpassYour MariaDB password
    dbnamegaseous
    igaboression_ClientIdYour Twitch Client ID
    igaboression_ClientSecretYour Twitch Client Secret

    Attach Persistent Volumes

    Persistent storage is essential for Gaseous Server. Add the following volumes:

    Mount PathRecommended SizePurpose
    /games100+ GBROM file storage (adjust based on collection size)
    /config1 GBApplication configuration
    /data5 GBApplication data and cache

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will:

    • Detect your Dockerfile automatically
    • Build the container image
    • Attach the persistent volumes
    • Start the Gaseous Server container
    • Provision an HTTPS certificate

    Access Gaseous Server

    Once deployment completes, access your Gaseous Server instance at https://your-app-name.klutch.sh. The first-time setup wizard will guide you through initial configuration.

Initial Setup and Configuration

First-Time Setup

When you first access Gaseous Server:

  1. Create your admin account
  2. Configure basic settings
  3. Set up your first library scan location

Adding ROM Libraries

To add your game collection:

  1. Navigate to Settings → Libraries
  2. Add a new library path (e.g., /games/nes)
  3. Configure platform settings for the library
  4. Initiate a library scan
  5. Wait for metadata to be fetched from IGDB

Organize your ROMs for optimal detection:

/games/
├── nes/
│   ├── Super Mario Bros.nes
│   └── The Legend of Zelda.nes
├── snes/
│   ├── Super Mario World.sfc
│   └── Chrono Trigger.sfc
├── genesis/
│   ├── Sonic the Hedgehog.md
│   └── Streets of Rage.md
├── gba/
│   ├── Pokemon Ruby.gba
│   └── Metroid Fusion.gba
└── n64/
    ├── Super Mario 64.z64
    └── Ocarina of Time.z64

Platform Configuration

Configure each platform for proper emulation:

  1. Go to Settings → Platforms
  2. Select a platform
  3. Configure emulator core preferences
  4. Set default controller mappings
  5. Adjust emulation settings

Playing Games

Browser-Based Emulation

To play a game:

  1. Browse your library and select a game
  2. Click Play to launch the emulator
  3. Configure controller settings if needed
  4. Enjoy retro gaming in your browser

Controller Support

Gaseous Server supports various input methods:

Input TypeNotes
KeyboardDefault mappings provided
GamepadUSB/Bluetooth controllers supported
TouchVirtual gamepad for mobile devices

Save States

The emulator supports save states:

  • Create save states during gameplay
  • Load previous save states
  • States are stored persistently

User Management

Creating Users

Add additional users to your Gaseous Server instance:

  1. Go to Settings → Users
  2. Click Add User
  3. Set username and password
  4. Configure permissions

Authentication Options

Gaseous Server supports multiple authentication methods:

MethodDescription
LocalUsername/password with optional 2FA
GoogleOAuth2 with Google accounts
MicrosoftOAuth2 with Microsoft accounts
OIDCGeneric OpenID Connect providers

Two-Factor Authentication

Enable 2FA for enhanced security:

  1. Go to your account settings
  2. Enable Two-Factor Authentication
  3. Scan the QR code with your authenticator app
  4. Enter the verification code

Production Best Practices

Security Recommendations

  • Strong Passwords: Use strong passwords for all accounts
  • Enable 2FA: Activate two-factor authentication
  • API Credentials: Keep IGDB credentials secure
  • Regular Updates: Keep Gaseous Server updated
  • Access Control: Limit user registrations if publicly accessible

Storage Planning

ROM collections can be large:

  • NES/SNES: Typically small (KB to a few MB each)
  • PlayStation/N64: Larger files (hundreds of MB each)
  • Disc-based Systems: Can be several GB per game
  • Plan Accordingly: Allocate storage based on your collection

Performance Optimization

  • Library Size: Large libraries may need more memory
  • Scanning: Initial scans are resource-intensive
  • Metadata Cache: Ensure adequate cache storage
  • Concurrent Users: Scale resources for multiple players

Backup Strategy

Protect your configuration:

  1. Database Backups: Regularly back up MariaDB
  2. Configuration: Back up the /config directory
  3. ROM Backups: Maintain copies of your ROM files
  4. Save States: Back up user save data

Troubleshooting Common Issues

Games Not Detected

Symptoms: ROMs don’t appear after scanning.

Solutions:

  • Verify ROM file formats are supported
  • Check file permissions on ROM directories
  • Ensure library paths are correctly configured
  • Try manual file identification

Metadata Not Loading

Symptoms: Games appear without cover art or descriptions.

Solutions:

  • Verify IGDB API credentials are correct
  • Check for API rate limiting
  • Try manually triggering metadata refresh
  • Verify internet connectivity

Emulator Not Working

Symptoms: Games won’t launch or crash immediately.

Solutions:

  • Check browser compatibility (Chrome/Firefox recommended)
  • Verify ROM file isn’t corrupted
  • Try a different emulator core
  • Check browser console for errors

Application Won’t Start

Symptoms: Container exits or fails health checks.

Solutions:

  • Verify database connection settings
  • Check that all required environment variables are set
  • Review startup logs for errors
  • Ensure MariaDB is running and accessible

Additional Resources

Conclusion

Deploying Gaseous Server on Klutch.sh gives you a powerful ROM management platform with automatic builds, persistent storage, and secure HTTPS access. The combination of Gaseous Server’s comprehensive features and Klutch.sh’s deployment simplicity means you can focus on enjoying your game collection rather than managing infrastructure.

With automatic metadata fetching, browser-based emulation, and support for multiple platforms, Gaseous Server transforms your ROM collection into an accessible, organized library. Whether you’re preserving gaming history or reliving classic titles, Gaseous Server on Klutch.sh provides the foundation for a reliable, always-available retro gaming platform.