Half-Life 2: Deathmatch Docker Container
This Docker container provides a fully configured Half-Life 2: Deathmatch game server that automatically downloads and updates the game via SteamCMD, supports file overlaying using OverlayFS, and includes optional SourceMod/MetaMod support.
Quick Start
services:
halflife2deathmatch-deathmatch:
image: lancommander/halflife2deathmatch:latest
container_name: halflife2deathmatch-deathmatch
ports:
- 27016:27015/udp
- 27021:27020/udp
- 27080:80 # For FastDL support
volumes:
- "/data/Servers/Half-Life 2 - Deathmatch:/config"
environment:
STEAM_APP_UPDATE: "true"
START_ARGS: "-game hl2mp -console +map dm_lockdown"
INSTALL_SOURCEMOD: "true"
cap_add:
- SYS_ADMIN
security_opt:
- apparmor:unconfined
restart: unless-stopped
Configuration Options
Ports
The container exposes the following ports:
- 27015/udp - Main game server port (default). Clients connect to this port to join the server.
- 27020/udp - SourceTV port (optional). Used for game broadcasting and recording.
- 80/tcp - HTTP file server port (optional). Used for serving game files to clients (See FastDL).
Port Mapping: In the example configuration, ports are mapped as:
27016:27015/udp- Maps host port 27016 to container port 2701527021:27020/udp- Maps host port 27021 to container port 2702027080:80- Maps host port 27021 to container port 27020
You can customize these mappings based on your network requirements. If you're running multiple servers, use different host ports for each instance.
Volumes
The container requires a volume mount for the /config directory, which stores:
- Server/ - Game files downloaded by SteamCMD (auto-created)
- Overlay/ - Custom files that overlay on top of the game directory
- Merged/ - OverlayFS merged view (auto-created)
- Scripts/ - Custom PowerShell scripts for hooks
Example:
volumes:
- "/data/Servers/Half-Life 2 - Deathmatch:/config"
The host path can be:
- An absolute path (Windows:
C:\data\..., Linux:/data/...) - A relative path (e.g.,
./config:/config) - A named volume (e.g.,
hl2dm-server-data:/config)
Important: The mounted directory must be writable by the container.
Environment Variables
| Variable | Description | Default | Required |
|---|---|---|---|
STEAM_APP_UPDATE | Enable automatic game updates on startup ("true"/"false") | "true" | No |
START_ARGS | Arguments used to start the game server | "-game hl2mp -console +map dm_lockdown" | No |
INSTALL_SOURCEMOD | Enable SourceMod/MetaMod installation ("true"/"false") | "false" | No |
SOURCEMOD_VERSION | SourceMod version to install | "1.12.0-git7221" | No |
METAMOD_VERSION | MetaMod version to install | "1.12.0-git1219" | No |
GAME_MOD | Game modification directory | "hl2mp" | No |
STEAM_APP_UPDATE
Controls whether SteamCMD updates the game server on container startup.
"true"- Automatically download/update the game server"false"- Skip updates (useful for offline operation or faster startup)
Example:
environment:
STEAM_APP_UPDATE: "true"
START_ARGS
Arguments passed to the game server executable at startup.
Default:
START_ARGS: "-game hl2mp -console +map dm_lockdown"
Customization Examples:
Basic server with custom map:
START_ARGS: "-game hl2mp -console +map dm_lockdown"
Server with max players and public IP:
START_ARGS: "-game hl2mp -console +map dm_lockdown +maxplayers 24 +sv_lan 0 +ip 0.0.0.0"
Server with RCON password:
START_ARGS: "-game hl2mp -console +map dm_lockdown +rcon_password mypassword"
Common Server Parameters:
+map <mapname>- Set the starting map (e.g.,dm_lockdown,dm_overwatch)+maxplayers <number>- Maximum number of players (default: 32)+sv_lan 0- Enable internet play (0 = internet, 1 = LAN only)+ip <address>- Server IP address (use0.0.0.0for all interfaces)+port <port>- Server port (default: 27015)+rcon_password <password>- RCON password for remote administration+hostname "<name>"- Server name displayed in server browser
INSTALL_SOURCEMOD
Enables automatic installation of SourceMod and MetaMod:Source, which provide plugin support and enhanced server administration.
"true"- Install SourceMod and MetaMod"false"- Skip SourceMod installation
When enabled, the container will:
- Download and install MetaMod:Source (required dependency)
- Download and install SourceMod
- Place all files in
/config/Overlay/hl2mp/addons/
Example:
environment:
INSTALL_SOURCEMOD: "true"
Security Options
The container requires elevated privileges to use OverlayFS for file overlaying.
cap_add: SYS_ADMIN
Adds the SYS_ADMIN capability, which is required for mounting OverlayFS. This is the recommended approach as it provides minimal necessary privileges.
cap_add:
- SYS_ADMIN
security_opt: apparmor:unconfined
On Ubuntu hosts with AppArmor enabled, you may need to disable AppArmor restrictions for the container. This is often necessary for OverlayFS to function properly.
security_opt:
- apparmor:unconfined
Alternative Options:
If you prefer less security but simpler configuration, you can use privileged mode:
privileged: true
Note: Privileged mode grants the container extensive access to the host system and is less secure than using cap_add: SYS_ADMIN.
Restart Policy
restart: unless-stopped
This ensures the container automatically restarts if it stops unexpectedly, but won't restart if you manually stop it.
Other options:
no- Never restartalways- Always restart, even after manual stopon-failure- Restart only on failure
Directory Structure
The /config directory contains the following structure:
/config/
├── Server/ # Game files from SteamCMD (auto-created)
│ └── hl2mp/ # Half-Life 2: Deathmatch game directory
├── Overlay/ # Custom files overlay (your modifications)
│ └── hl2mp/
│ ├── addons/ # SourceMod/MetaMod installation location
│ │ ├── sourcemod/
│ │ │ ├── plugins/ # Place .smx plugin files here
│ │ │ ├── configs/ # SourceMod configuration files
│ │ │ └── ...
│ │ └── metamod/
│ ├── maps/ # Custom maps
│ ├── cfg/ # Server configuration files (server.cfg, etc.)
│ └── ...
├── Merged/ # OverlayFS merged view (auto-created)
├── .overlay-work/ # OverlayFS work directory (auto-created)
└── Scripts/
└── Hooks/ # Custom PowerShell scripts for hooks
SourceMod Configuration
Installing Plugins
Once SourceMod is installed, add plugins by placing compiled .smx files in:
/config/Overlay/hl2mp/addons/sourcemod/plugins/
Example:
# Copy plugin to the overlay directory
cp my_plugin.smx "/data/Servers/Half-Life 2 - Deathmatch/Deathmatch/Overlay/hl2mp/addons/sourcemod/plugins/"
# Restart the container to load the plugin
docker restart halflife2deathmatch-deathmatch
SourceMod Configuration Files
Place SourceMod configuration files in:
/config/Overlay/hl2mp/addons/sourcemod/configs/
Common configuration files:
admins_simple.ini- Admin user configurationcore.cfg- Core SourceMod settingsdatabase.cfg- Database configuration (if using database features)
Server Configuration
Place server configuration files in:
/config/Overlay/hl2mp/cfg/
Example server.cfg:
hostname "My Half-Life 2: Deathmatch Server"
sv_lan 0
maxplayers 24
rcon_password "your_rcon_password"
Match Statistics
The server can report the matches played on it to LANCommander, with the
LANCommander match statistics plugin.
The plugin is built into the image and needs SourceMod (INSTALL_SOURCEMOD). It is turned on when
MATCH_STATS_SERVER_URL and MATCH_STATS_TOKEN are set, and is then copied into hl2mp/addons/sourcemod/ on every
start. The core plugin loads the Half-Life 2: Deathmatch module itself. Turned off, the plugin's files are removed again.
| Variable | Description | Default |
|---|---|---|
MATCH_STATS_ENABLED | auto: on when MATCH_STATS_SERVER_URL and MATCH_STATS_TOKEN are set. true or false | auto |
MATCH_STATS_SERVER_URL | The LANCommander server, e.g. http://lancommander.lan:1337. Only http:// works on Linux | (empty) |
MATCH_STATS_TOKEN | A LANCommander access token with the Report matches scope (Profile → Access Tokens). It isn't written to any file | (empty) |
MATCH_STATS_GAME_ID | The game's id in LANCommander | (empty) |
MATCH_STATS_SERVER_ID | This server's id in LANCommander, if LANCommander manages it | (empty) |
MATCH_STATS_REPORTER_NAME | How the server is named in LANCommander | (hostname) |
MATCH_STATS_MIN_PLAYERS | Human players needed before a match is recorded | (1) |
MATCH_STATS_MODE | The mode reported. Empty lets the game module decide | (empty) |
MATCH_STATS_RECORD_BOTS | Record bots as players (true/false) | (true) |
MATCH_STATS_RECORD_CHAT | Record chat messages (true/false) | (false) |
MATCH_STATS_ATTACH_DEMOS | Upload SourceTV demos recorded with tv_record (true/false) | (true) |
The settings are written to hl2mp/cfg/sourcemod/lancommander.cfg as lc_* cvars on every start. Settings left
empty aren't written, so they and the plugin's other lc_* cvars (see its README) can be set in
hl2mp/cfg/sourcemod/sourcemod.cfg instead. A lancommander.cfg you put in Overlay/hl2mp/cfg/sourcemod/ yourself
is left alone.
sm_lc_status on the server console or over RCON shows the match being recorded and how delivery is going. Reports
that couldn't be delivered yet are kept in Overlay/hl2mp/addons/sourcemod/extensions/.interposer/Matches/ and sent
once LANCommander can be reached.
OverlayFS
The container uses Linux OverlayFS to merge the base game files with your custom files:
- Lower layer:
/config/Server(base game files from SteamCMD) - Upper layer:
/config/Overlay(your custom files) - Merged view:
/config/Merged(where the game server runs from)
Benefits:
- Replace files without modifying the base installation
- Add custom content (maps, plugins, configs)
- No file copying required - OverlayFS is a union filesystem
- Easy updates - base game files can be updated without losing customizations
If OverlayFS cannot be mounted (e.g., missing privileges), the container will fall back to using /config/Server directly and log a warning.
Troubleshooting
Container Won't Start
-
Check logs:
docker logs halflife2deathmatch-deathmatch -
Verify permissions: Ensure the mounted volume is writable:
# Linux
chmod -R 755 "/data/Servers/Half-Life 2 - Deathmatch/Deathmatch"
# Windows
# Ensure the directory has proper permissions in Windows -
Check security options: Ensure
cap_add: SYS_ADMINis set, or useprivileged: true
Game Server Not Starting
-
Verify START_ARGS: Check that
START_ARGScontains valid server arguments:START_ARGS: "-game hl2mp -console +map dm_lockdown" -
Check server directory: Verify that game files were downloaded:
docker exec halflife2deathmatch-deathmatch ls -la /config/Server/hl2mp -
Review server logs: Check container logs for server startup messages and errors
SourceMod Not Loading
-
Verify installation: Ensure
INSTALL_SOURCEMOD: "true"is set (with quotes in YAML) -
Check installation directory:
docker exec halflife2deathmatch-deathmatch ls -la /config/Overlay/hl2mp/addons/sourcemod -
Verify MetaMod: Check that MetaMod is installed:
docker exec halflife2deathmatch-deathmatch ls -la /config/Overlay/hl2mp/addons/metamod.vdf -
Check server console: Look for SourceMod loading messages in the container logs
OverlayFS Warnings
If you see warnings about OverlayFS:
-
Verify capabilities: Ensure
cap_add: SYS_ADMINis present in your docker-compose.yml -
Check AppArmor: On Ubuntu, add
security_opt: apparmor:unconfined -
Alternative: Use
privileged: true(less secure but simpler)
Failed to open bin/dedicated_srv.so on first boot
On the very first start the overlay is mounted before SteamCMD has created Server/bin, so srcds_run can't find the engine. The automatic restart (restart: unless-stopped) picks it up on the next start; no action is needed.
Port Already in Use
If you get port binding errors:
-
Check for existing containers:
docker ps -a -
Use different ports: Change the port mapping in docker-compose.yml:
ports:
- 27017:27015/udp # Use a different host port -
Stop conflicting containers:
docker stop <container-name>
Permission Errors
The container runs as a non-root user. If you encounter permission errors:
-
Check file ownership:
docker exec halflife2deathmatch-deathmatch ls -la /config -
Verify volume mount: Ensure the host directory is accessible and writable
-
Review logs: Check container logs for specific permission error messages
Advanced Usage
Custom Hooks
You can create custom PowerShell scripts that execute at various points in the container's lifecycle. Place scripts in:
/config/Scripts/Hooks/{HookName}/
Available hooks:
PreSteamInstall- Before SteamCMD runsPostSteamInstall- After SteamCMD completesPreInstallSourceMod- Before SourceMod installationPostInstallSourceMod- After SourceMod installation
Example hook script (/config/Scripts/Hooks/PostSteamInstall/10-CustomSetup.ps1):
Write-Host "Running custom setup..."
# Your custom commands here
HTTP File Server
The container includes an optional HTTP file server (port 80) for serving game files to clients. This is useful for fast downloads of custom maps and content.
The file server is configured via environment variables:
HTTP_FILESERVER_ENABLED- Enable/disable the file serverHTTP_FILESERVER_WEB_ROOT- Root directory for file servingHTTP_FILESERVER_FILE_PATTERN- Pattern for files to serve
Multiple Server Instances
To run multiple Half-Life 2: Deathmatch servers on the same host:
-
Use different container names:
container_name: halflife2deathmatch-server1 -
Use different ports:
ports:
- 27016:27015/udp
- 27021:27020/udp -
Use different volume mounts:
volumes:
- "/data/Servers/Half-Life 2 - Deathmatch/Server1:/config" -
Use different maps/names:
environment:
START_ARGS: "-game hl2mp -console +map dm_overwatch +hostname 'Server 1'"