How I Built and Run My BombSquad Server with Docker
Running a game server sounds simple until you actually try it. You need a stable environment, a way to push updates without taking everything down, persistent player data, custom mods, and ideally the ability to test changes without touching production. This post covers how I solved all of that for my BombSquad server using Docker and a small collection of shell scripts.
The project is called Less Server Scripts and it currently runs on BombSquad 1.7.51 (API 9).
Why Docker
BombSquad's headless server is a binary that runs on Linux. You could just drop it on a VPS and run it directly, but that approach gets messy fast. When you update a mod, you have to restart the process manually. If the server crashes, nothing brings it back. And if you want to test something without breaking the live server, you're stuck.
Docker solves most of these problems by isolating the server inside a container. The environment is reproducible, the restart policy handles crashes automatically, and you can run a dev instance and a production instance on the same machine without them ever conflicting.
What You Need
Before anything else, make sure you have the following on your VPS:
- Docker and Docker Compose installed
- At least 1 GB of RAM (2 GB recommended)
- A Linux machine — AWS, Google Cloud, Azure, or any standard VPS works
On your local machine, you'll need Python 3.13 to run the deployment script.
Getting Started
Clone the repository and copy the environment template:
//[title="terminal"]
git clone --depth=1 https://github.com/danigomezdev/bombsquad --branch server-scripts
cd bombsquad
cp .env.example .env
nano .env
The .env file controls where and how your server runs. The key variables are:
//[title=".env"]
ENVIRONMENT="production"
SERVER_NAME="less_east_c1"
PARTY_NAME="Teams @ Less"
PORT="43210"
SSH_HOST="ubuntu@your-server"
SSH_KEY="~/.ssh/yourkey.pem"
SERVER_NAME becomes the Docker container and image name, so each server instance needs a unique value here. PARTY_NAME is what players see in the server browser.
Deploying to the Server
There are two built-in deployment presets:
//[title="terminal"]
./deploy.sh dev # deploys to /home/ubuntu/tests/test on port 6666
./deploy.sh prod # deploys to /home/ubuntu/servers/less on port 43210
The dev mode overwrites everything, including player stats, which makes it ideal for testing. The prod mode preserves player data and stats, so it's safe to run against a live server. If neither preset fits, edit your .env and run ./deploy.sh without arguments.
Managing the Server
Once deployed, everything is managed through docker.sh on the remote machine. SSH in, navigate to the server directory, and run it:
//[title="terminal"]
ssh -i ~/.ssh/yourkey.pem ubuntu@your-server
cd /home/ubuntu/servers/less
./docker.sh
You get an interactive menu:
//[title="docker.sh menu"]
1) Start server (build if needed)
2) Stop server
3) Restart server (config/mods changes only)
4) Rebuild and restart (code changes)
5) View logs (live)
6) View logs (last 200 lines)
7) Force full rebuild (clean rebuild)
8) Server status
9) Enter container shell
0) Stop and remove container
The distinction between options 3 and 4 matters. If you only changed a config file or a mod script, option 3 restarts in about 5 seconds. If you changed actual server code or installed a new dependency, option 4 rebuilds the image first, which takes 30 to 60 seconds. Option 7 is the nuclear option — it throws everything away and builds from scratch.
Project Structure
Here's what the repository looks like after deployment:
//[title="project structure"]
bombsquad-server/
├── dist/
│ ├── ba_data/ # Python modules (bacommon, efro)
│ └── ba_root/
│ └── mods/
│ ├── characters/ # Custom character mods
│ ├── chathandle/ # Chat commands system
│ ├── features/ # Server features
│ │ ├── afk_check.py
│ │ ├── announcement.py
│ │ ├── discord_bot.py
│ │ ├── fire_flies.py
│ │ ├── team_balancer.py
│ │ └── votingmachine.py
│ ├── playersdata/ # Player profiles and roles
│ ├── serverdata/ # Server logs and data
│ ├── stats/ # Player statistics
│ └── tools/ # Utility scripts
├── bombsquad_server # Main server script
├── config.toml # Server configuration
├── docker-compose.yml
├── docker.sh
├── deploy.sh
└── Dockerfile
The mods/features/ directory is where most of the custom behavior lives. Each feature is a standalone Python module that the server loads at startup.
Basic Configuration
Edit config.toml for the core server settings:
//[title="config.toml"]
party_name = "Teams @ Less Server"
port = 43210
max_party_size = 7
session_type = "teams"
team_names = ["Blue", "Red"]
For the more advanced features, there's a separate setting.json file inside the mods directory:
//[title="dist/ba_root/mods/setting.json"]
{
"character_chooser": { "enable": true },
"autoTeamBalance": true,
"afk_remover": { "enable": true },
"autoNightMode": {
"enable": true,
"startTime": "18:00",
"endTime": "06:00"
}
}
Night mode automatically changes the server lighting after 6 PM and restores it at 6 AM. The AFK remover kicks players who go idle so they don't block slots for others.
Player Roles
The role system controls who can do what on the server. Roles are stored in a JSON file and identified by BombSquad account IDs:
//[title="dist/ba_root/mods/playersdata/roles.json"]
{
"owners": ["pb-YourAccountID"],
"admins": [],
"vips": []
}
To get your own account ID, use the /getaccountid command in-game. Owners have full permissions, admins can moderate players, and VIPs get any extra privileges you configure.
Chat System
The chat handler supports a few prefix conventions that change how messages are delivered:
- Comma prefix (
,message) — sends the message only to your team - Dot prefix (
.message) — displays the message as a prominent popup for all players
Beyond that, there's a full command system for in-game actions, and an optional profanity filter you can toggle in the settings.
Discord Integration
There's a Discord bot module included that links the server to a Discord channel. It can relay game events, display server status, and let you interact with the server from Discord. Configuration lives inside discord_bot.py in the features directory.
Statistics and Leaderboard
Player stats are tracked automatically and persist across sessions. The top 5 players appear on a live in-game leaderboard. There's also a web interface where you can browse full stats from a browser. Stats can be reset on a schedule if you want periodic seasons.
Running Multiple Servers
Each server instance is completely isolated by its directory name. You can run two servers on the same machine without them interfering:
//[title="terminal"]
cd /home/ubuntu/servers/server_1
./docker.sh
cd /home/ubuntu/servers/server_2
./docker.sh
Each gets its own container name, Docker image, network, volumes, and port derived from its config.toml. The only constraint is that each server needs a unique port.
Common Issues
"ModuleNotFoundError: No module named 'bacommon'" The Python modules weren't copied into the image. Rebuild with option 4 or 7 from the management menu.
"Container exists but is stopped" Use option 1 to start. It auto-removes the stopped container and recreates it cleanly.
"Port already in use"
Change the PORT value in config.toml or your .env file. Each server needs a unique UDP port.
Closing Thoughts
The combination of Docker, a simple shell menu, and a clean deployment script makes the day-to-day reality of running a game server much less painful. Changes to mods or config take seconds to apply. Code updates rebuild in under a minute. Player data survives restarts and redeployments. And the whole thing can be replicated on a new machine just by cloning the repo and running the deploy script.
If you play BombSquad and want to try the server, look for Teams @ Less in the server browser.
