Overview

A quick mental model of how SourceBans++ fits together, so the rest of the guide reads as "wire up these named pieces" rather than a wall of commands. Skip ahead if you already run an ops-grade SourceMod stack.

The big picture

SourceBans++ has two halves that share a single database:

                    +-------------------------+
                    |     Web panel (PHP)     |
                    |  /var/www/sourcebans/   |
                    +-----------+-------------+
                                |
                                |  reads & writes
                                v
                       +--------+--------+
                       |    Database     |
                       | MySQL / MariaDB |
                       +--------+--------+
                                ^
                                |  reads & writes
                                |
                    +-----------+-------------+
                    | SourceMod plugins (.smx)|
                    |   on each game server   |
                    +-------------------------+

The web panel is what your admins log into. It's a PHP app that talks to the database directly. You install it once, on any host that can run PHP and reach the database (typically the same host).

The SourceMod plugins run on each of your game servers (one install per game server). They enforce bans in-game by disconnecting banned players and muting players in comm blocks. They also write new admin actions back to the database so the panel sees them too.

Both halves share one database. There is no API contract between the plugin and the panel; they coordinate through shared SQL tables. This matters because:

• The plugin and panel can run on different hosts, as long as both can reach the database.
• Adding a new game server is a database row, not a network handshake.
• A short database outage is the only thing that can desync them.

Things you'll set up

A first-time install walks through, in order:

1. A database: MariaDB or MySQL, hosted wherever's convenient. See Database setup.
2. The web panel: pick an install path below.
3. One or more game servers: add each to the panel to get a ServerID. See Adding a server.
4. The SourceMod plugins: drop them onto each game server, edit databases.cfg and sourcebans.cfg, restart the server. See Plugin setup.
5. Your admin team: create admins, group them, hand out permissions. See Admins & groups.

After that you're in day-to-day operation: people get banned, you review appeals, you tune permissions.

Pick an install path

We ship three install paths for the panel. The plugin side is the same regardless. These options only differ in how the web panel gets stood up.

Tarball / shared hosting

Best when: you already run a webserver, share hosting with other apps, or want full control over PHP, Apache, or nginx config. The traditional install path: download a release zip, upload via FTP / cPanel / SSH, walk the install wizard once.

Step it out with the tarball quickstart.

Docker

Best when: you own the host, want one-command upgrades (docker compose pull && up -d), automatic TLS, or reproducible deploys across machines. Ships a multi-arch image (ghcr.io/sbpp/sourcebans-pp) signed with Sigstore cosign.

Step it out with the Docker quickstart.

App platform (one click)

Best when: you don't want to manage a host at all and your panel doesn't need custom configuration. Deploy buttons for DigitalOcean App Platform, Railway, Render, and Fly.io are tracked in issue #1382.

Note

The image speaks every platform-conventional knob: PORT injection, DATABASE_URL parsing, /health.php probes, and *_FILE secrets. Until the deploy buttons land, point any platform that runs container images at ghcr.io/sbpp/sourcebans-pp:latest and set the env vars from the Docker quickstart.

Key concepts

A handful of terms come up over and over in the panel and in this guide.

Admin: a panel user with a Steam ID, an email, and a set of permission flags. Admins also exist server-side (the plugin reads them from the panel into SourceMod), so a panel admin with the right flags is automatically an in-game admin too.

Group: a named bundle of permission flags. Most installs assign permissions to groups (e.g. "Moderators", "Senior admins") and then assign admins to groups, instead of granting permissions per-admin.

Server: a single game-server instance registered in the panel. Each one has an IP:port, an RCON password, and a numeric ServerID that the SourceMod plugin uses to tag its writes.

Ban: a Steam ID or IP record with a duration, reason, and the admin who issued it. Permanent bans have no expiry. Temporary bans expire on their own.

Comm block: a mute or gag. Mutes silence voice; gags silence text chat. Same concept as a ban, applied to communication rather than connection.

RCON: Source's remote-control protocol. The panel uses it to push commands (kick, ban, reload) to a running game server. The password lives in the panel and in the game server's config. Getting them out of sync is the most common "panel can't talk to the server" cause.

What's next

Check the requirements PHP version, DB engine, SourceMod version, Docker version, whichever path you picked above.

Tarball quickstart Fresh tarball install: database, web upload, wizard, plugin config.

Docker quickstart docker compose up to a fully running panel with persistent volumes and automatic TLS.