Web Frontend – Linux
Running the bot on Windows? Use the Windows guide instead.
DCSServerBot comes with a web frontend that lets you manage your nodes and servers from a browser. It is part of the WebService and is turned off by default.
What people can do once logged in depends on their role:
| Role | What they can do |
|---|---|
| Admin | Edit node and server configurations |
| DCS Admin | Edit server configurations only |
managed_by roles (see servers.yaml) |
See and manage only the servers assigned to them (useful for hosters) |
The setup has three parts:
- Steps 0–2: turn the frontend on and log in on your own machine or network.
- Step 3 (optional): put it on the internet safely, behind HTTPS, using nginx. If you prefer Caddy, see Step 4.
- Troubleshooting: a table of common problems and fixes at the end.
Note
Commands in this guide are written for Debian / Ubuntu (apt, ufw). On Fedora, RHEL, Rocky or Alma, use dnf instead of apt, firewall-cmd instead of ufw, and put nginx configs in /etc/nginx/conf.d/ (see the notes in Step 3).
Step 0 – Pick your login method
There are two ways for people to log in. Pick one:
| Option A: Discord login | Option B: Local users | |
|---|---|---|
| How people log in | With their Discord account | With a username/password you create |
| Needs | A domain name with HTTPS (e.g. https://bot.example.com), see Step 3 |
Nothing extra; plain HTTP works on your LAN |
| Roles come from | Your Discord roles (via the roles: mapping in services/bot.yaml) |
The roles you write next to each user |
| Recommended for | Communities with several admins | Single admin, testing, LAN-only setups |
Note
Discord only allows its login to send people back to an https:// address, which is why Option A needs HTTPS.
If you want Option A, do Step 3 first (or at least alongside), because Discord login won't work until HTTPS does.
All bot commands below are run in a terminal, as the user that runs the bot, from your DCSServerBot folder, for example:
cd ~/DCSServerBot
They use the bot's own Python, which lives in a hidden folder in your home directory, normally ~/.dcssb-<node name>, where the node name defaults to your hostname. Check where yours is:
ls -d ~/.dcssb*
The commands below assume ~/.dcssb-$(hostname). If ls showed a different name, use that instead.
Step 1 – Generate a session secret (both options)
The session secret is a random password the website uses to sign login cookies. You only need it once, and nobody types it in.
~/.dcssb-$(hostname)/bin/python -c "import secrets; print(secrets.token_urlsafe(48))"
Copy the long line it prints. You'll paste it into webservice.yaml below.
Caution
Treat the session secret like a password. Anyone who has it can forge logins.
Option A – Discord login (HTTPS)
A1. Set up OAuth2 in the Discord Developer Portal
- Open the Discord Developer Portal and select your bot's application.
- Go to OAuth2.
- Copy the Client ID.
- Copy the Client Secret. You may have to press Reset Secret to see it.
- Under Redirects, press Add Redirect (or "Add another") and enter:
Replace
https://your-dns-name/auth/discord/callbackyour-dns-namewith your real domain. It must matchpublic_base_urlin the next step exactly: samehttps://, same spelling, no trailing slash. - Press Save Changes.
A2. Edit config/services/webservice.yaml
Create the file if it doesn't exist. Replace everything in <...> with your values, and keep the quotes.
# config/services/webservice.yaml
DEFAULT:
listen: 127.0.0.1 # only the reverse proxy on this machine can reach the bot (see Step 3)
port: 9876
debug: false
frontend: true # THIS ENABLES THE FRONTEND
session:
secret: '<your session secret from Step 1>'
https_only: true # correct for HTTPS
auth:
public_base_url: https://your-dns-name # no trailing slash; must match the Discord redirect
discord:
enabled: true
client_id: '<your client id>'
client_secret: '<your client secret>'
Then continue with Step 2 and Step 3.
Option B – Local users (HTTP)
B1. Create a user
Run this for each person who should have access, changing the username and role:
~/.dcssb-$(hostname)/bin/python -m services.webservice.auth.local --hash --username "MyFancyUser" --roles Admin
- It asks for the password twice. Nothing is shown while you type; that's normal.
- It then prints a small YAML block containing a
password_hash. You'll copy the hash into the file below. - Valid roles are
AdminandDCS Admin. ForDCS Admin, keep the quotes:--roles "DCS Admin".
B2. Edit config/services/webservice.yaml
Create the file if it doesn't exist. Replace everything in <...> with your values.
# config/services/webservice.yaml
DEFAULT:
listen: 0.0.0.0 # 0.0.0.0 = reachable from other machines on your network; use 127.0.0.1 for this machine only
port: 9876
debug: false
frontend: true # THIS ENABLES THE FRONTEND
session:
secret: '<your session secret from Step 1>'
https_only: false # MUST be false when using plain HTTP, or logins won't stick
auth:
public_base_url: http://<your-ip>:9876 # the address people type in their browser
local:
enabled: true
users:
- username: MyFancyUser
password_hash: '<hash from B1>'
roles: [Admin]
- username: AnotherUser
password_hash: '<hash from B1>'
roles: [DCS Admin]
Add one - username: block per person. The - username, password_hash and roles lines must stay lined up exactly as shown, because YAML is picky about spaces.
Warning
With plain HTTP, passwords travel unencrypted. Only use this on a network you trust (LAN or VPN). To use local users over the internet, do Step 3 and switch to the HTTPS settings shown there.
Step 2 – Restart and open the website
- Restart DCSServerBot.
- Open the website on the bot machine: http://localhost:9876/. On a headless server, test with
curl -I http://localhost:9876/instead; any HTTP response means it's up. - Log in with your username/password (Option B). Option A users can't log in yet; continue with Step 3.
Option B only: to reach it from another machine on your network at http://<bot-machine-ip>:9876/, allow the port through the firewall. Limit it to your LAN, adjusting the subnet to yours:
sudo ufw allow from 192.168.1.0/24 to any port 9876 proto tcp
Caution
Never forward port 9876 on your router, and never open it to the whole internet (ufw allow 9876 without from). If you want access from outside your network, use Step 3.
Step 3 – Serve it on the internet with HTTPS (nginx reverse proxy)
A reverse proxy is a small web server that sits in front of the bot. Browsers connect to it over HTTPS on the normal web ports (80/443), and it passes the traffic on to the bot on 127.0.0.1:9876, a port that is never exposed to the outside world.
Browser ──HTTPS (443)──▶ nginx (on the bot machine) ──HTTP──▶ DCSServerBot (127.0.0.1:9876)
not reachable from outside
This step uses nginx for the proxy and certbot for a free, auto-renewing Let's Encrypt certificate.
Tip
Prefer Caddy? Caddy handles certificates by itself and needs less setup. Do 3.1, 3.3 and 3.7 below, then follow Step 4 instead of 3.2, 3.4, 3.5 and 3.6.
3.1 What you need
| Requirement | Why | How |
|---|---|---|
A domain or subdomain, e.g. bot.example.com |
Certificates are issued for names, not IPs | Any registrar. A subdomain of a domain you already own is fine |
| A DNS A record pointing that name to your public IP | So browsers find your server | In your DNS provider's panel. Find your public IP with curl -4 ifconfig.me |
| Dynamic DNS, if your IP changes | Keeps the A record correct | Use your DNS provider's dynamic DNS feature or a DDNS updater such as ddclient |
| Ports 80 and 443 reachable from the internet | 80 is used to get and renew the certificate, 443 to serve the site | Home server: forward TCP 80 and 443 on your router to the machine's LAN IP. VPS: also open them in your provider's cloud firewall, if it has one |
| Local firewall allowing 80 and 443 | Same reason | See 3.3 |
Note
Using Cloudflare for DNS? Set the record to DNS only (grey cloud) for the first setup, so the certificate request reaches your server directly. You can switch to Proxied (orange cloud) afterwards, but then set Cloudflare's SSL/TLS mode to Full (strict).
Note
Can't forward ports (some ISPs, mobile/Starlink connections, CGNAT)? Then a direct reverse proxy won't be reachable from outside. Your options are a VPN between you and the bot machine, or a tunnel service. Both are outside the scope of this guide.
3.2 Install nginx and certbot
sudo apt update
sudo apt install -y nginx certbot
sudo systemctl enable --now nginx
Remove the default "Welcome to nginx" site so it doesn't get in the way:
sudo rm -f /etc/nginx/sites-enabled/default
Create the folder certbot will use to prove you own the domain:
sudo mkdir -p /var/www/certbot
3.3 Open the firewall for 80 and 443
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status
Important
If ufw status says inactive, make sure SSH is allowed before you enable it, or you can lock yourself out of a remote server:
sudo ufw allow OpenSSH
sudo ufw enable
If you added the LAN rule for port 9876 in Step 2 and no longer need it, remove it:
sudo ufw delete allow from 192.168.1.0/24 to any port 9876 proto tcp
Fedora / RHEL: use sudo firewall-cmd --permanent --add-service=http --add-service=https and then sudo firewall-cmd --reload.
3.4 Phase 1 nginx config (HTTP only, to get the certificate)
nginx refuses to start if a config points to certificate files that don't exist yet. So the setup happens in two phases: first HTTP only, to get the certificate, then HTTPS.
Create /etc/nginx/sites-available/dcsserverbot (for example with sudo nano /etc/nginx/sites-available/dcsserverbot) with this content, using your own domain:
# /etc/nginx/sites-available/dcsserverbot (PHASE 1: HTTP only)
server {
listen 80;
listen [::]:80;
server_name bot.example.com;
# Let's Encrypt validation files (written by certbot)
location /.well-known/acme-challenge/ {
root /var/www/certbot;
}
# Everything else goes to HTTPS
location / {
return 301 https://$host$request_uri;
}
}
Enable it, test, and reload:
sudo ln -s /etc/nginx/sites-available/dcsserverbot /etc/nginx/sites-enabled/dcsserverbot
sudo nginx -t
sudo systemctl reload nginx
sudo nginx -t must say syntax is ok and test is successful. If it doesn't, fix the error it names before reloading.
Fedora / RHEL: there is no sites-available. Save the file as /etc/nginx/conf.d/dcsserverbot.conf instead and skip the ln -s line.
3.5 Get the certificate with certbot
sudo certbot certonly --webroot -w /var/www/certbot -d bot.example.com --deploy-hook "systemctl reload nginx"
It asks for your email (for expiry warnings) and to accept the terms. When it's done, your certificate is in:
/etc/letsencrypt/live/bot.example.com/fullchain.pem ← certificate + chain
/etc/letsencrypt/live/bot.example.com/privkey.pem ← private key
The certbot package installs a timer that renews the certificate automatically and reloads nginx afterwards, thanks to --deploy-hook. Check that renewal will work with:
sudo certbot renew --dry-run
You don't need to do anything else for renewals; just keep port 80 open.
3.6 Phase 2 nginx config (HTTPS)
Replace the whole content of /etc/nginx/sites-available/dcsserverbot (Fedora/RHEL: /etc/nginx/conf.d/dcsserverbot.conf) with the full config, using your own domain:
# /etc/nginx/sites-available/dcsserverbot (PHASE 2: HTTPS)
# Needed for WebSocket connections, if the frontend uses them
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
# Port 80: certificate renewals + redirect to HTTPS
server {
listen 80;
listen [::]:80;
server_name bot.example.com;
location /.well-known/acme-challenge/ {
root /var/www/certbot;
}
location / {
return 301 https://$host$request_uri;
}
}
# Port 443: the actual website, passed through to DCSServerBot
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name bot.example.com;
ssl_certificate /etc/letsencrypt/live/bot.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/bot.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
location / {
proxy_pass http://127.0.0.1:9876;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
Test and reload:
sudo nginx -t
sudo systemctl reload nginx
Note
Fedora / RHEL with SELinux: nginx isn't allowed to connect to the bot by default, and you'll get 502 Bad Gateway. Allow it once with:
sudo setsebool -P httpd_can_network_connect 1
3.7 Point the bot at the proxy
In config/services/webservice.yaml, the bot must listen only locally and know its public HTTPS address.
Option A (Discord login): use the A2 file exactly as shown; it is already set up for this.
Option B (local users) over the internet: change your B2 file to this:
# config/services/webservice.yaml
DEFAULT:
listen: 127.0.0.1 # only the reverse proxy on this machine can reach the bot
port: 9876
debug: false
frontend: true # THIS ENABLES THE FRONTEND
session:
secret: '<your session secret from Step 1>'
https_only: true # true now, because browsers connect over HTTPS
auth:
public_base_url: https://bot.example.com # your domain, no trailing slash, no port
local:
enabled: true
users:
- username: MyFancyUser
password_hash: '<hash from B1>'
roles: [Admin]
- username: AnotherUser
password_hash: '<hash from B1>'
roles: [DCS Admin]
Restart DCSServerBot after saving. Then open https://bot.example.com from your phone on mobile data (not your Wi-Fi). That proves it works from the outside.
3.8 nginx starts with the system
The systemctl enable --now nginx from 3.2 already makes nginx start at boot. Useful commands for later:
| Task | Command |
|---|---|
| Check the config for errors | sudo nginx -t |
| Apply config changes | sudo systemctl reload nginx |
| Restart nginx | sudo systemctl restart nginx |
| See whether nginx is running | systemctl status nginx |
| Read the error log | sudo tail -n 50 /var/log/nginx/error.log |
| List certificates and expiry dates | sudo certbot certificates |
Step 4 – Alternative: Caddy instead of nginx
Caddy gets and renews HTTPS certificates by itself, so it replaces both nginx and certbot. Do 3.1, 3.3 and 3.7 from Step 3, then:
- Install Caddy. On Debian 12+ and Ubuntu 24.04+ it's in the standard repositories:
sudo apt update
sudo apt install -y caddy
For other or older distributions, follow https://caddyserver.com/docs/install. The package sets Caddy up as a service that starts at boot.
- Replace the whole content of
/etc/caddy/Caddyfilewith this, using your domain:
# /etc/caddy/Caddyfile
bot.example.com {
reverse_proxy 127.0.0.1:9876
}
- Apply it and watch the log:
sudo systemctl reload caddy
sudo journalctl -u caddy -f
Within a minute it should report that it obtained a certificate for your domain. Stop watching with Ctrl+C, then check https://bot.example.com from mobile data.
After editing the Caddyfile later, run sudo systemctl reload caddy again.
Note
Don't run nginx and Caddy at the same time; both want ports 80 and 443. If you tried nginx first, stop it with sudo systemctl disable --now nginx.
Security notes
- Only ports 80 and 443 should ever be reachable from the internet, and only via the reverse proxy. Never forward or open 9876 or any other DCSServerBot port.
- Keep
webservice.yamlprivate. It contains your session secret, client secret and password hashes. Lock it down withchmod 600 config/services/webservice.yaml. - Use strong passwords for local users; anyone on the internet can reach the login page.
- Use
debug: falseunless you're actively troubleshooting.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
No such file or directory for ~/.dcssb-…/bin/python |
The bot's environment has a different name, or you're logged in as a different user than the one running the bot | Run ls -d ~/.dcssb* as the bot's user and use that path |
No module named services |
Command not run from the DCSServerBot folder | cd into the DCSServerBot folder first |
| Page loads on the bot machine but not from other machines (LAN) | Firewall, or listen: 127.0.0.1 |
Add the LAN ufw rule from Step 2; use listen: 0.0.0.0 (LAN setups only) |
| Login seems to work, then you're sent straight back to the login page | https_only doesn't match how you connect |
false for plain HTTP, true behind HTTPS |
| Discord shows Invalid OAuth2 redirect_uri | Redirect in the Developer Portal ≠ public_base_url + /auth/discord/callback |
Make them match character for character (https, domain, no port, no trailing slash) |
| Logged in but can't edit anything | Your account has no Admin / DCS Admin role | Option A: check the roles: mapping in services/bot.yaml. Option B: check roles: for your user |
| Bot fails to start after editing the file | YAML indentation or unquoted special characters | Compare your file line by line with the example; keep secrets in quotes |
nginx: [emerg] cannot load certificate |
Phase 2 config used before the certificate exists, or a typo in the domain in the path | Go back to the Phase 1 config, finish 3.5, check sudo ls /etc/letsencrypt/live/ |
bind() to 0.0.0.0:80 failed (98: Address already in use) |
Another program is using port 80 or 443 (Apache, Caddy, another nginx…) | Find it with sudo ss -tlnp \| grep -E ':80\|:443' and stop or disable it |
| certbot says the challenge failed | Port 80 not reachable, DNS not pointing to your public IP yet, Cloudflare proxy (orange cloud) on, or the Phase 1 config not active | Check port forwarding / cloud firewall; check the record with dig +short bot.example.com; set Cloudflare to "DNS only"; run sudo nginx -t and reload |
| Site works on your network but not from outside (or the reverse) | Your router doesn't support "NAT loopback", or port forwarding is missing | Always test from mobile data. If outside works, the setup is fine |
| 502 Bad Gateway | nginx can't reach the bot | Make sure the bot is running and that the port: in webservice.yaml matches proxy_pass (9876). On Fedora/RHEL, see the SELinux note in 3.6 |
| Browser shows a certificate warning | The certificate doesn't match the name, or Cloudflare SSL mode is wrong | Use exactly the domain from your nginx config; with Cloudflare proxy on, use Full (strict) |
| Changes to the nginx config have no effect | nginx wasn't reloaded, or you edited the wrong file | sudo nginx -t && sudo systemctl reload nginx; check that sites-enabled/dcsserverbot points to your file with ls -l /etc/nginx/sites-enabled/ |