UT2004 Podman Server

A containerised Unreal Tournament 2004 dedicated server using the official OldUnreal installer, with the MLP UT2004 modpack and HudCompanion baked in.

On first run the container downloads and installs the game directly into your bind-mounted /data directory. Subsequent runs skip installation and start the server immediately.

---

Requirements

• Podman 4.4+
• A valid UT2004 server CD key

---

Repository Layout

ut2004-podman/
├── .gitmodules
├── Dockerfile
├── start_server.sh
├── compress.sh
├── ut2004.container          ← Podman quadlet (systemd unit)
├── README.md
├── upstream/
│   └── OldUnreal/            ← git submodule
│       └── Linux/
│           └── install-ut2004.sh
├── mlp_ut2004_modpack_v02.zip
└── HudCompanion-v1.2.zip

---

Getting Started

1. Clone the repository

git clone --recurse-submodules https://forgejo.dragast.me/ut2004-podman.git
cd ut2004-podman

If you already cloned without --recurse-submodules:

git submodule update --init

2. Build the image

The build is lean and fast - it only installs runtime dependencies and copies scripts. The game itself is downloaded and installed on first run.

podman build --layers -t ut2004 .

---

Running the Server

Option A — Direct podman run

podman run -d \
  -v /your/host/path:/data \
  -p 7777:7777/udp \
  -p 7778:7778/udp \
  -p 7787:7787/udp \
  -e CD_KEY=XXXX-XXXX-XXXX-XXXX \
  -e PUID=1000 \
  -e PGID=1000 \
  --name ut2004 \
  ut2004

Replace /your/host/path with the directory where you want the game files to live on your host.

Follow first-run installation progress with:

podman logs -f ut2004

Option B - Podman Quadlet (recommended)

A quadlet file lets systemd manage the container as a service, with automatic restart on crash and optional start on boot.

1. Edit ut2004.container

Set your host data path and CD key:

Volume=/your/host/path:/data:rw,z
Environment=CD_KEY=XXXX-XXXX-XXXX-XXXX

Adjust any other environment variables as needed (see Configuration below).

2. Install the quadlet file

cp ut2004.container ~/.config/containers/systemd/

3. Reload systemd and start the service

systemctl --user daemon-reload
systemctl --user start ut2004

4. Enable auto-start on boot

systemctl --user enable ut2004
loginctl enable-linger $USER

loginctl enable-linger allows the service to start at boot even without an active login session.

Useful service commands:

# Check status
systemctl --user status ut2004

# Follow logs
journalctl --user -u ut2004 -f

# Stop / restart
systemctl --user stop ut2004
systemctl --user restart ut2004

---

Data Directory Layout

After first run, your host directory will contain:

/your/host/path/
├── server/          ← base game files + mods, installed on first run
│   └── System/
│       ├── UT2004.ini -> /data/config/UT2004.ini   ← symlink
│       └── ucc-bin
├── addons/          ← drop custom maps and mutators here
│   ├── Animations/
│   ├── Maps/
│   ├── Music/
│   ├── Saves/
│   ├── Sounds/
│   ├── StaticMeshes/
│   ├── System/
│   └── Textures/
└── config/          ← all .ini files and cdkey live here, edit freely
    ├── UT2004.ini
    ├── Game.ini
    ├── User.ini
    └── cdkey

Never edit files in server/System/ directly — the .ini files there are symlinks into config/. Edit the files in config/ instead and restart the server to apply changes.

---

Adding Custom Maps and Mutators

Drop files into the appropriate subdirectory under addons/ and restart the server. The addon paths are automatically registered in UT2004.ini on first run:

File type	Directory
Maps	addons/Maps/
Mutators / packages	addons/System/
Textures	addons/Textures/
Static meshes	addons/StaticMeshes/
Animations	addons/Animations/
Sounds	addons/Sounds/
Music	addons/Music/

---

Configuration

All configuration is done via environment variables passed to podman run or set in the quadlet file.

Variable	Default	Description
PUID	1000	User ID to run the server as
PGID	1000	Group ID to run the server as
CD_KEY	(empty)	UT2004 server CD key (required)
ISO_URL	draga.st mirror	URL to download the UT2004 ISO from
MAP_NAME	DM-Antalus	Initial map
GAME_TYPE	xGame.xDeathMatch	Game type
BASE_MUTATORS	HudCompanion.MutHudCompanion	Mutators baked into the image, always active
MUTATORS	(empty)	Additional mutators appended to BASE_MUTATORS
SERVER_START_COMMAND	(empty)	Override the entire server start command
SERVER_START_EXTRAS	(empty)	Extra parameters appended to the server command
COMPRESS_DIR	(empty)	If set, compresses server files into this directory for a redirect server
TZ	(system)	Timezone for logging

Mutators

BASE_MUTATORS contains mutators that are always active because they are installed in the image (HudCompanion). MUTATORS is an extension point for the user — the two are combined automatically:

# Adds SomeMutator alongside HudCompanion
-e MUTATORS=SomeMutator.MutSomeMutator

# Result: HudCompanion.MutHudCompanion,SomeMutator.MutSomeMutator

---

Updating the OldUnreal Installer

The OldUnreal installer is included as a git submodule. To update it:

git submodule update --remote upstream/OldUnreal
git add upstream/OldUnreal
git commit -m "Update OldUnreal installer"
podman build --layers -t ut2004 .

---

Ports

Port	Protocol	Description
7777	UDP	Game port (required)
7778	UDP	Query port (game port + 1)
7787	UDP	GameSpy query port (game port + 10)