Deploying Hypersomnia

Introduction

Hypersomnia is a competitive multiplayer top-down shooter that blends the tactical gameplay of Counter-Strike with the fast-paced aesthetics of Hotline Miami. Written entirely from scratch in C++ without using a game engine, Hypersomnia delivers extreme dynamics, nostalgic pixelated visuals, and tight competitive gameplay in a remarkably lightweight package of only 50 MB.

The game is 100% free and open-source under the AGPL-3.0 license, with no paywalls, microtransactions, or premium features. What makes Hypersomnia unique for self-hosters is that the entire server infrastructure can be self-hosted - the editor, game server, and masterserver (server list keeper) are all embedded in the same executable across all operating systems.

Key highlights of Hypersomnia:

• Competitive Gameplay: Fast-paced tactical shooter with bomb defusal and team deathmatch modes
• No Game Engine: Built from scratch in bare C++ for maximum performance and minimal footprint
• Cross-Platform: Runs on Linux, Windows, macOS, and even in web browsers
• Self-Hostable Infrastructure: Host game servers, masterservers, and even the level editor
• Built-in Port Forwarding: Game can automatically forward ports for easy hosting
• Low Resource Usage: Only 50 MB installation size with minimal memory requirements
• Active Development: Regular updates with new features, maps, and balance changes
• Open Source: AGPL-3.0 licensed with community contributions welcome

This guide walks through deploying a Hypersomnia game server on Klutch.sh using Docker, enabling you to host multiplayer matches for your community.

Why Deploy Hypersomnia on Klutch.sh

Deploying Hypersomnia on Klutch.sh provides several advantages for hosting game servers:

Simplified Deployment: Klutch.sh handles the container orchestration automatically. Push your Dockerfile to GitHub and your game server deploys without manual server configuration.

Persistent Storage: Attach persistent volumes for server configuration, maps, and game data. Your server settings survive container restarts and redeployments.

Low Latency: Klutch.sh infrastructure provides consistent network performance essential for competitive gaming.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments to keep your server current.

Scalable Resources: Allocate CPU and memory based on expected player count. Start small for private matches and scale up for community servers.

Always-On Availability: Your game server remains accessible 24/7 without managing your own hardware.

Prerequisites

Before deploying Hypersomnia on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your server configuration
• Basic familiarity with Docker and containerization concepts
• The Hypersomnia game client for testing your server

Understanding Hypersomnia Server Architecture

Hypersomnia’s architecture is uniquely self-contained:

Single Executable: The game server, masterserver, and editor are all contained within the same executable. This simplifies deployment significantly.

UDP-Based Networking: Game traffic uses UDP for low-latency communication essential for competitive gameplay.

Masterserver Integration: Servers can register with the official masterserver to appear in the public server browser, or you can run a private server.

Map System: Custom maps and game modes can be loaded from the server’s data directory.

Preparing Your Repository

To deploy Hypersomnia on Klutch.sh, create a GitHub repository containing your Dockerfile and server configuration.

Repository Structure

hypersomnia-server/
├── Dockerfile
├── server_config.cfg
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ubuntu:22.04

# Install dependencies
RUN apt-get update && apt-get install -y \
    wget \
    libgl1-mesa-glx \
    libx11-6 \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Download and extract Hypersomnia
WORKDIR /opt/hypersomnia
RUN wget -O hypersomnia.tar.gz https://github.com/TeamHypersomnia/Hypersomnia/releases/latest/download/Hypersomnia-Linux.tar.gz \
    && tar -xzf hypersomnia.tar.gz \
    && rm hypersomnia.tar.gz \
    && chmod +x Hypersomnia

# Create directories for server data
RUN mkdir -p /data/maps /data/logs

# Copy server configuration
COPY server_config.cfg /opt/hypersomnia/

# Set environment variables
ENV SERVER_NAME=${SERVER_NAME:-"Klutch.sh Hypersomnia Server"}
ENV MAX_PLAYERS=${MAX_PLAYERS:-16}
ENV GAME_MODE=${GAME_MODE:-bomb_defusal}

# Expose UDP port for game traffic
EXPOSE 8412/udp

# Run the dedicated server
CMD ["./Hypersomnia", "--dedicated-server", "--server-config", "server_config.cfg"]

Server Configuration

Create a server_config.cfg file with your server settings:

server_name "Klutch.sh Hypersomnia Server"
max_players 16
game_mode bomb_defusal
friendly_fire 0
round_time 180
warmup_time 30

Environment Variables Reference

Variable	Required	Default	Description
SERVER_NAME	No	Klutch.sh Server	Display name for your server
MAX_PLAYERS	No	16	Maximum concurrent players
GAME_MODE	No	bomb_defusal	Game mode (bomb_defusal, team_deathmatch)
SERVER_PASSWORD	No	-	Password to join the server
REGISTER_MASTERSERVER	No	true	Register with public server list

Deploying Hypersomnia on Klutch.sh

Once your repository is prepared, follow these steps to deploy your game server:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile server_config.cfg .dockerignore
git commit -m "Initial Hypersomnia server configuration"
git remote add origin https://github.com/yourusername/hypersomnia-server.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 “hypersomnia” or “game-server”.

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 Hypersomnia Dockerfile.

Configure TCP Traffic

Hypersomnia uses UDP for game traffic. In the deployment settings:

• Select TCP as the traffic type
• Set the external port to 8000
• The internal port maps to 8412 (Hypersomnia’s default)

Note: For UDP-based game servers, you may need to configure port forwarding appropriately for your deployment scenario.

Set Environment Variables

In the environment variables section, configure your server:

Variable	Value
SERVER_NAME	Your server’s display name
MAX_PLAYERS	16 (or your preferred limit)
GAME_MODE	bomb_defusal or team_deathmatch

Attach Persistent Volumes

Add the following volumes for persistent storage:

Mount Path	Recommended Size	Purpose
/data	5 GB	Server configuration, maps, and logs

Deploy Your Application

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

• Detect your Dockerfile automatically
• Build the container image with the latest Hypersomnia release
• Attach the persistent volumes
• Start the game server
• Provide connection details

Connect to Your Server

Once deployment completes, launch Hypersomnia on your local machine and connect to your server using the provided address and port.

Server Administration

Managing Your Server

Hypersomnia servers can be managed through:

• Configuration Files: Modify server_config.cfg and redeploy
• In-Game Console: Server operators can use console commands during matches
• Remote Administration: Configure admin passwords for remote server control

Game Modes

Hypersomnia supports several competitive game modes:

Mode	Description
Bomb Defusal	Counter-Strike style plant/defuse objectives
Team Deathmatch	Classic team-based elimination
Gun Game	Progress through weapons with each kill
Free For All	Every player for themselves

Adding Custom Maps

To add custom maps to your server:

1. Download map files from the Hypersomnia community
2. Add them to your repository’s maps directory
3. Update your Dockerfile to copy maps to the server
4. Redeploy to apply changes

Troubleshooting Common Issues

Players Cannot Connect

Symptoms: Players see the server but cannot join.

Solutions:

• Verify the server is running in the Klutch.sh dashboard
• Check that port configuration matches your deployment settings
• Ensure firewall rules allow UDP traffic

Server Not Appearing in Browser

Symptoms: Server doesn’t show in the public server list.

Solutions:

• Verify REGISTER_MASTERSERVER is enabled
• Check network connectivity to the masterserver
• Review server logs for registration errors

High Latency

Symptoms: Players experience lag during matches.

Solutions:

• Ensure adequate CPU and memory allocation
• Check player geographic distribution
• Monitor server resource usage in the dashboard

Additional Resources

• Official Hypersomnia Website
• Hypersomnia GitHub Repository
• Hypersomnia Discord Community
• Play Hypersomnia in Browser
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying a Hypersomnia game server on Klutch.sh gives you a dedicated competitive gaming environment with reliable uptime and consistent performance. The game’s lightweight nature and self-contained architecture make it an excellent choice for self-hosted game servers.

Whether you’re hosting private matches with friends or running a community server for competitive play, Hypersomnia on Klutch.sh provides the infrastructure for fast-paced tactical gameplay without the complexity of traditional game server hosting.