Dockerized Battlefield 2 server based on insanity54/bf42-dock, with the retail server or with OpenBF2. The base image is debian:bullseye-slim for the retail server and debian:trixie-slim for OpenBF2, and was tested on Linux containers in Windows 10 WSL2 and Debian 11. Uses multi-stage builds to keep the image sizes down.
- Docker
- Docker Compose (optional)
Different server variations are placed in the images folder, each complete in its own folder. To create your own, you can copy one of the existing images to use as a base, and then place your custom files in the assets/build/bf2 folder to overwrite any existing files.
The first three images run the retail server and keep their server files and settings in volumes, as described next. The OpenBF2 images work differently, see The OpenBF2 images.
Initial settings or passwords can be set using environment variables. Persisted files like settings, logs and demos are put in the /volume directory in the container using symbolic links and should be mapped to a host directory. If you want to have full visibility of the server files you can also map the /home/bf2/srv folder of the container.
To use these images on a remote host like a VPS you can either use the snippets below to build and run or you can build the images locally and then push them to a container registry like Docker Hub or Azure Container Registry (public or private).
Running multiple servers on the same host can be done by changing the ports in the environment variables and the mapped host port. For this use case I prefer using Docker Compose, an example is listed further down.
- Battlefield 2 server (1.5.3153.0)
The basic image to run a Battlefield 2 server. It runs as a LAN server, since the stock server aborts in internet mode without GameSpy (use one of the BF2Hub images to play online), but it can be used as a base. Set ENV_INTERNET=1 to start it in internet mode anyway.
docker build -t nihlen/bf2-docker/default https://github.com/nihlen/bf2-docker.git#master:images/default
docker run --name bf2server -v <host directory>:/volume -p 4711:4711/tcp -p 4712:4712/tcp -p 16567:16567/udp -p 27901:27901/udp -p 29900:29900/udp nihlen/bf2-docker/default:latest
- BF2Hub Unranked (R3)
- Updated PunkBuster
- ModManager (2.2c)
- Automatic demo hosting (nginx)
Uses BF2Hub to play online. The RCON password is set using environment variable ENV_RCON_PASSWORD. If you want to persist the demos on the host you can use -v <host directory>:/var/www/html/demos and use -e ENV_DEMOS_URL='<host address>' to provide demo urls after finished rounds.
docker build -t nihlen/bf2-docker/bf2hub-pb-mm https://github.com/nihlen/bf2-docker.git#master:images/bf2hub-pb-mm
docker run --name bf2server -v <host directory>:/volume -e ENV_RCON_PASSWORD='rconpw123' -e ENV_DEMOS_URL='http://www.example.com:80/' -p 80:80/tcp -p 4711:4711/tcp -p 4712:4712/tcp -p 16567:16567/udp -p 27901:27901/udp -p 29900:29900/udp nihlen/bf2-docker/bf2hub-pb-mm:latest
- BF2CC Daemon (1.4.2446)
Runs with bf2ccd.exe using Mono. The RCON and BF2CC Daemon passwords are set using environment variables ENV_RCON_PASSWORD and ENV_BF2CCD_PASSWORD.
docker build -t nihlen/bf2-docker/bf2hub-pb-mm-bf2cc https://github.com/nihlen/bf2-docker.git#master:images/bf2hub-pb-mm-bf2cc
docker run --name bf2server -it -v <host directory>:/volume -e ENV_RCON_PASSWORD='rconpw123' -e ENV_BF2CCD_PASSWORD='bf2ccdpw123' -e ENV_DEMOS_URL='http://www.example.com:80/' -p 80:80/tcp -p 4711:4711/tcp -p 4712:4712/tcp -p 16567:16567/udp -p 27901:27901/udp -p 29900:29900/udp nihlen/bf2-docker/bf2hub-pb-mm-bf2cc:latest
- OpenBF2 server, an open source implementation of the Battlefield 2 server
- BF2Hub (OpenBF2-BF2Hub)
- Automatic demo hosting (nginx)
The stock server files with the server binaries replaced by OpenBF2 and its BF2Hub module, to play online. It has no PunkBuster (OpenBF2 has none) and no ModManager, and runs the stock admin script (sv.adminScript "default") with its RCON on port 4711. The RCON password is set using environment variable ENV_RCON_PASSWORD; without it nobody can log in. The base image is debian:trixie-slim, since OpenBF2 needs a newer glibc.
OpenBF2 publishes no binaries. These are a build of nihlen/OpenBF2, a fork with the server extension interface and two TV missile settings that are off by default, taken from the release zip of openbf2-server-ext. BF2Hub's GameSpy domain is compiled into them, so the server reports to BF2Hub's master server. Set ENV_INTERNET=0 for a LAN server.
docker build -t nihlen/bf2-docker/openbf2 https://github.com/nihlen/bf2-docker.git#master:images/openbf2
docker run --name bf2server -v <host directory>:/volume -e ENV_SERVER_NAME='bf2-docker' -e ENV_RCON_PASSWORD='rconpw123' -e ENV_DEMOS_URL='http://www.example.com:80/' -p 80:80/tcp -p 4711:4711/tcp -p 16567:16567/udp -p 29900:29900/udp nihlen/bf2-docker/openbf2:latest
- Server extension (openbf2-server-ext), the admin channel to BF2WebAdmin
The openbf2 image, including its RCON, with one more OpenBF2 module, libserverext.so. BF2WebAdmin (branch admin-channel) kicks, bans and runs console commands over its admin channel, and bans stay in the server's own banlist.con. Set the four ENV_ADMIN_* variables below to connect it; without them the module dials nowhere.
docker build -t nihlen/bf2-docker/openbf2-serverext https://github.com/nihlen/bf2-docker.git#master:images/openbf2-serverext
docker run --name bf2server -v <host directory>:/volume -e ENV_SERVER_NAME='bf2-docker' -e ENV_DEMOS_URL='http://www.example.com:80/' -e ENV_ADMIN_CONNECT='bf2wa.example.com:4300' -e ENV_ADMIN_SERVER_ID='203.0.113.10:16567' -e ENV_ADMIN_KEY='<hex key from BF2WebAdmin>' -e ENV_ADMIN_CERT_SHA256='<pin of BF2WebAdmin's certificate>' -p 80:80/tcp -p 16567:16567/udp -p 29900:29900/udp nihlen/bf2-docker/openbf2-serverext:latest
This applies to openbf2, openbf2-serverext and the netsky-openbf2-* images. Their Dockerfile, build.sh, setup.sh and run.sh are the same files in every folder. What an image is comes from its data: assets/build/bf2/ (the settings, mods/bf2/openbf2.con and admin scripts), maps.txt and levels/.
Modules. mods/bf2/openbf2.con loads the modules before Python starts (openbf2.addModDll "bf2hub", and "serverext" in the images with the server extension), so the server runs start.sh instead of start_bf2hub.sh. A module that an image's openbf2.con does not load is left out of the image.
Settings on every start. The server files are part of the image and are not copied to a volume. run.sh renders the settings from templates (/home/bf2/templates) and the environment variables on every start, so a new image or a changed variable takes effect when the container is recreated. Don't edit settings in the container.
| Variable | Default | |
|---|---|---|
ENV_SERVER_NAME |
bf2-docker |
sv.serverName |
ENV_MAX_PLAYERS |
16 |
sv.maxPlayers |
ENV_SERVER_PORT |
16567 |
sv.serverPort, the game port (udp) |
ENV_GAMESPY_PORT |
29900 |
sv.gameSpyPort, the query port (udp) |
ENV_INTERNET |
1 |
sv.internet, 0 for a LAN server that is not listed on the master server |
ENV_DEMOS_URL |
http://example.com/demos/ |
sv.demoIndexURL and sv.demoDownloadURL |
ENV_CONTENT_CHECK |
1 |
0 turns off the content check, see below |
ENV_RCON_PASSWORD |
none | The password of the stock admin script's RCON: 4711/tcp in the container, and rcon login <password> in the game's console. Printable characters without spaces or =. Without it the port is open but nobody can log in. Only in an image that runs the stock admin script (openbf2, openbf2-serverext); with another admin script, like the netsky images', there is no RCON and the variable is ignored |
ENV_TV_AIM_FROM_MISSILE |
0 (off, retail) |
OpenBF2 vars.set tv-aim-from-missile, metres: a TV missile's aim point that would make it stop turning (a wall beside it) is cast again from the server's missile when the client's camera is at most this far from it |
ENV_TV_TURN_BEHIND |
0 (off, retail) |
OpenBF2 vars.set tv-turn-behind, 1: a TV missile keeps turning towards an aim point beside or behind it instead of flying straight |
ENV_TV_KEEP_AIM_ON_RELOAD |
0 (off, retail); 1 in netsky-openbf2-2v2 and netsky-openbf2-chopper-mayhem (their serversettings.con) |
OpenBF2 vars.set tv-keep-aim-on-reload, 1: a TV missile keeps its aim point when its launcher reloads, about a second after the shot; in retail it stops turning there until the next steering input |
ENV_TV_INPUT_QUEUE |
0 (off, retail) |
OpenBF2 vars.set tv-input-queue, 1 to 8, experimental: while a player guides a TV missile, the server keeps that many of the player's inputs waiting. The client's view of the missile is that many ticks (33 ms each) fresher, and the same from flight to flight; in retail the depth is left to chance, 0 to 4. Steering is not delayed, the player's other inputs are |
ENV_TV_TRACE |
0 |
1 switches on OpenBF2's TV missile trace, a diagnostic: when each steering input reached the server and when each missile update was sent to a player, the depth of the gunner's input queue in each tick, at most 32768 rows per start, appended to /volume/tv-trace.log |
ENV_SPONSOR_VARS |
none (the netsky images have their own) | sponsortext variables, added as $vars:<value>$ at {{sponsor_vars}} in the template's sv.sponsorText, which server browsers read from the GameSpy query. key=value pairs separated by ; (escape =, ;, $ and \ in a value with \); no double quotes. Set but empty: no variables. An image sets its own default with a line rem default ENV_SPONSOR_VARS=<value> in its serversettings.con |
Only with the server extension (openbf2-serverext, netsky-openbf2-*):
| Variable | Default | |
|---|---|---|
ENV_ADMIN_CONNECT |
none | BF2WebAdmin's admin channel listener, <host>:<port> (e.g. bf2wa.nihlen.net:4300). The module dials it over TLS |
ENV_ADMIN_SERVER_ID |
none | The server's id in BF2WebAdmin (Server.ServerId, e.g. <public ip>:<game port>) |
ENV_ADMIN_KEY |
none | The server's admin key in BF2WebAdmin (Server.AdminKey), 32 to 128 hex digits |
ENV_ADMIN_CERT_SHA256 |
none | The pin of BF2WebAdmin's certificate, 64 hex digits (BF2WebAdmin.Server --admin-pin, or the adminCertSha256 line of --admin-cert-create) |
ENV_BOT_PORT |
16700 |
The module's bot channel, always on 127.0.0.1 inside the container. It has no authentication, never publish it |
Set all four ENV_ADMIN_* variables or none. Without them the module dials nowhere (the log says admin channel: off), and run.sh refuses to start with only some of them, or with any of them in an image without the module. The module's other settings are fixed in the rendered serverext.cfg: stepMode 0, allowTeleport 0, allowRoundRestart 0, adminAllowConsole 1.
Other settings and the map list. The variables cover what differs between servers. For anything else, without building an image, put your own serversettings.con or maplist.con in /volume/templates/: run.sh uses it instead of the image's template and renders it the same way. Start from the image's file (assets/build/bf2/mods/bf2/settings/serversettings.con, or /home/bf2/templates/mods/bf2/settings/ in the container) and keep the {{...}} placeholders you want to set with variables. run.sh only reads this folder. Custom maps still need an image, see Custom maps.
Content check. With the four fingerprint files in mods/bf2 (std_archive.md5, std_archive_mod.md5, bst_archive.md5, bst_archive_mod.md5) the server compares the checksums a client reports of its game files and kicks a client with modified files. ENV_CONTENT_CHECK=0 removes them, for a server where players may use modified game files (a "nocheck" server). The check is not anti-cheat: the client computes the checksums itself. On a map without an archive.md5 in its folder the server compares only four small .con files and not the game archives. That is every custom map, since the build leaves a map's archive.md5 out unless it is in levels/<map>/.
What persists. Only /volume, mounted from the host or a named volume. /home/bf2/srv must not be mounted (a volume there would keep the server files of an older image), run.sh refuses to start if it is.
| Path | |
|---|---|
/volume/settings/banlist.con |
BF2's ban list |
/volume/demos/pending, /volume/demos/uploaded |
Demos being recorded, and the finished ones nginx serves at /demos/ (rotate_demo.py keeps 50) |
/volume/bf2.log |
The server console of this start, bf2.log.1 of the previous start |
/volume/logs |
Module logs (logs/bf2hub) |
/volume/templates |
Optional, yours: templates used instead of the image's (above) |
The rendered settings are not in /volume. A /volume from a retail image keeps its previous copies of maplist.con, modmanager.con and serversettings.con as <file>.old. mm_bans.xml and modmanager.log from an image with ModManager are not used and can be deleted. The module's own log lines go to docker logs.
services:
bf2-openbf2:
container_name: bf2-openbf2
image: nihlen/bf2-docker/openbf2-serverext
# BF2WebAdmin's .restartserver quits the server with exit code 0, which on-failure would not restart
restart: unless-stopped
environment:
- ENV_SERVER_NAME=bf2-docker #1
- ENV_MAX_PLAYERS=16
- ENV_SERVER_PORT=16567
- ENV_GAMESPY_PORT=29900
- ENV_DEMOS_URL=http://www.example.com:8000/
- ENV_ADMIN_CONNECT=bf2wa.example.com:4300
- ENV_ADMIN_SERVER_ID=203.0.113.10:16567
- ENV_ADMIN_KEY=<hex key from BF2WebAdmin>
- ENV_ADMIN_CERT_SHA256=<pin of BF2WebAdmin's certificate>
volumes:
- "/data/bf2/bf2-openbf2/volume:/volume"
ports:
- "8000:80/tcp"
- "16567:16567/udp"
- "29900:29900/udp"The OpenBF2 release. The binaries come from one zip, openbf2-serverext-<openbf2>-<module>-<bf2hub>-bf2hub.zip (the three commits), a release of openbf2-server-ext that is unpacked into bin/amd-64. Its source.txt is /home/bf2/srv/openbf2-source.txt in the image. To move to a new release, change the zip's URL in assets/build/assets.txt and its line in assets/build/assets.sha512 (the release's .zip.sha512 file is that line) in every OpenBF2 image. build.sh takes the zip's name from assets.txt.
- netsky-openbf2-2v2: 2v2 chopper server
- netsky-openbf2-chopper-mayhem: Chopper mayhem on Dalian Plant
- netsky-openbf2-dogfight: Dogfight server
- netsky-openbf2-inf: Infantry server, a placeholder with its settings and no image yet
Images used for the NeTskY servers, and an example of making your own: each is openbf2-serverext with its own data and nothing else.
serversettings.conandmaplist.con, with a description per server type insv.sponsorTextand the servers' ownENV_SPONSOR_VARSdefault (website=https://bf2.nihlen.net/;discord=https://discord.gg/DPaJaMKAc3;provider=bf2hub.com).- The admin script
admin/netsky.py(sv.adminScript "netsky"), a port of the one ModManager module the servers used,mm_autobalanceas it was configured (roundSwitch 1, no commander or squad balancing): a connecting player joins the team with fewer players, every player swaps teams at the end of a round, and withsv.autoBalanceTeam 1(off in these images) dying players and team changes are balanced. It writesnetsky: admin script loadedto the server console when it starts. - Custom maps (
maps.txt) and changes to maps (levels/), see Custom maps.
The 2v2 server without the content check ("nocheck") is netsky-openbf2-2v2 with ENV_CONTENT_CHECK=0. The retail netsky images (netsky-2v2, netsky-2v2-nocheck, netsky-chopper-mayhem, netsky-dogfight, netsky-inf) and bf2hub-pb-mm-webadmin, which they were based on, have been removed. They needed mm_webadmin.py, which BF2WebAdmin no longer supports.
Custom maps are downloaded during the build of an OpenBF2 image. List the map archive URLs in assets/build/maps.txt and their checksums in assets/build/maps.sha512. Each archive should contain a single map folder, like the ones on static.nihlen.net/bf2/maps. Only the server files are extracted, client.zip and archive.md5 are skipped.
Server-side changes to a map are placed in assets/build/levels/<map>. Files in levels/<map>/server.zip/ are updated inside the map's server.zip, so you only need to commit the changed files (e.g. levels/dalian_2_v_2/server.zip/GameModes/gpm_cq/16/GamePlayObjects.con). Other files, like archive.md5, are copied to the map folder as-is.
To simplify setting up multiple servers on the same host you can use Docker Compose. The image: property can point to a locally built image or a URL to your container registry of choice. Note that the game server port and gamespy port need to match in the environment variables and in the Docker port configuration.
Here is an example of running two retail servers on the same host (the OpenBF2 images have their own example above):
version: "3.3"
services:
bf2-docker-1-service:
container_name: bf2-docker-1
image: nihlen/bf2-docker/bf2hub-pb-mm
restart: on-failure
environment:
- ENV_SERVER_NAME=bf2-docker #1
- ENV_MAX_PLAYERS=16
- ENV_SERVER_PORT=16567
- ENV_GAMESPY_PORT=29900
- ENV_DEMOS_URL=http://www.example.com:8000/
- ENV_RCON_PASSWORD=rconpw123
volumes:
- "/data/bf2/bf2-docker-1/server:/home/bf2/srv"
- "/data/bf2/bf2-docker-1/volume:/volume"
ports:
- "8000:80/tcp"
- "4711:4711/tcp"
- "4712:4712/tcp"
- "16567:16567/udp"
- "27901:27901/udp"
- "29900:29900/udp"
bf2-docker-2-service:
container_name: bf2-docker-2
image: nihlen/bf2-docker/bf2hub-pb-mm-bf2cc
restart: on-failure
environment:
- ENV_SERVER_NAME=bf2-docker #2
- ENV_MAX_PLAYERS=4
- ENV_SERVER_PORT=16569
- ENV_GAMESPY_PORT=29901
- ENV_DEMOS_URL=http://www.example.com:8001/
- ENV_RCON_PASSWORD=rconpw123
- ENV_BF2CCD_PASSWORD=bf2ccdpw123
volumes:
- "/data/bf2/bf2-docker-2/server:/home/bf2/srv"
- "/data/bf2/bf2-docker-2/volume:/volume"
ports:
- "8001:80/tcp"
- "4721:4711/tcp"
- "4722:4712/tcp"
- "16569:16569/udp"
- "27911:27901/udp"
- "29901:29901/udp"Place the docker-compose.yml on the host and run docker-compose up -d --remove-orphans to create the containers. If you are not using a container registry then the images need to be built on the host first.
First set up Docker Desktop on Windows (WSL2).
Download the assets (see assets.txt) and put them in the images/*/assets/build/ folder so you don't need to redownload them on each build. Maps (see maps.txt) go in the images/*/assets/build/maps/ folder. Then make your changes in Dockerfile, build.sh, setup.sh and run.sh. Build and run with .\build.bat. Make sure Docker is set to use Linux containers.
Test your changes with tests/run.sh static and tests/run.sh build <image>, see tests. The image folders are copies of each other on purpose, so a change to a file that an image family shares has to be made in every folder of the family: the static checks fail if the OpenBF2 images' shared files differ. CLAUDE.md lists the families and the steps for common changes.
The CI workflow runs the static checks on every push and pull request. Images with changes in images/<image>/ are built and smoke tested (all images if tests/ or .github/ changed). A folder without a Dockerfile is not an image. Tested images are pushed to cr.nihlen.net/library/bf2-docker:<image>, overwriting the previous image. Images are only pushed from the branches in the PUSH_BRANCHES repository variable (default master), using the CR_USERNAME and CR_PASSWORD secrets. Since the image layers are larger than Cloudflare's 100 MB upload limit, the job joins the tailnet as tag:ci (a Tailscale federated identity credential in the TS_OAUTH_CLIENT_ID and TS_AUDIENCE secrets) and pushes to the same registry through its tailnet-only hostname cr-ts.nihlen.net. On the default branch it can also be run manually for selected images under Actions > CI > Run workflow.
Contributions to new or existing images are welcome if you want them public.