Skip to content

Web service

The webservice service runs an HTTP server inside the bot on the master node. It carries two things on one port:

  • the REST API used by the RestAPI plugin — served always;
  • the staff admin console — an HTML UI with pages, login and session — served only when you switch it on (see below).

It runs on the master node only, and starts after the service bus (services/webservice/service.py:24).


Turning it on

  1. Create the configuration file config/services/webservice.yaml with a DEFAULT: block. The service is switched on by the file: the loader reads config/services/<service>.yaml, and a missing file means no configuration and no service (core/services/base.py:177, services/webservice/service.py:29-56). Start from the sample: samples/services/webservice.yaml.

  2. Set frontend: true if you want the web console. Without it — the default — the service serves the REST API only: no pages, no login, no session cookie (schemas/webservice_schema.yaml:17, services/webservice/shell.py:75).

  3. Configure a login (auth:) and a session secret (session:) if you use the console. Without an auth: block every console page answers 403 (deny by default).

With the bot's validation: strict, a bad value in this file stops the service at load and names the problem; with validation: lazy (the default) it is logged (core/services/base.py:181-186).


Configuration

All keys live under DEFAULT: in config/services/webservice.yaml. Nothing here is derived from a request, so the same file behaves the same behind a reverse proxy as it does on localhost.

Key Default What it does Source
listen 0.0.0.0 Interface the HTTP server binds to. service.py:46
port 9876 TCP port. Must be 1024–65535 and unique per node. schemas/webservice_schema.yaml:10, core/utils/validators.py:170
debug false Serves /openapi.json, /docs and /redoc for API testing (loopback and private networks only — see the warning below). service.py:92, service.py:115-125
log_level info Default level filter of the console's log panel: info, warning or all. The same choice is available per page as ?level=. schemas/webservice_schema.yaml:22
frontend false Install the web console. false = REST API only. schemas/webservice_schema.yaml:17, shell.py:75
dashboard.live true Serve the live update stream (Server-Sent Events) on the dashboard. schemas/webservice_schema.yaml:33
dashboard.refresh_seconds 2 How often changed fragments are re-rendered and pushed, in seconds (1–60). schemas/webservice_schema.yaml:36
dashboard.stream_clients 16 Most concurrent live streams (1–256). schemas/webservice_schema.yaml:39
session.secret (unset → random per start) Signs the session cookie. Unset means every restart signs everyone out. schemas/webservice_schema.yaml:49, session.py:221
session.cookie_name dcssb_session Session cookie name. schemas/webservice_schema.yaml:50, session.py:48
session.max_age 86400 Session lifetime in seconds. schemas/webservice_schema.yaml:53
session.https_only (unset → derived from listen) The Secure flag on the session cookie. Unset: false on a loopback-only bind, true on anything else. schemas/webservice_schema.yaml:59, session.py:140-169
session.same_site lax Cookie SameSite: lax, strict or none. Keep lax — strict makes every OAuth login fail. schemas/webservice_schema.yaml:63, session.py:201-212
auth.public_base_url (none) The public origin (scheme + host) the console is reachable at. Redirect URIs are built from this, never from a request. schemas/webservice_schema.yaml:73
auth.local.enabled false Enable username/password login. schemas/webservice_schema.yaml:80
auth.local.users[].username (required) The account name. schemas/webservice_schema.yaml:87
auth.local.users[].password_hash (required) A PBKDF2 hash — never a plaintext password. schemas/webservice_schema.yaml:90
auth.local.users[].roles (required) Role names of the bot's role model (Admin, DCS Admin, …). An unknown name is refused at startup. schemas/webservice_schema.yaml:93-97
auth.local.users[].scope (unset = unrestricted) The managed_by values this account may see and act on (the web-only equivalent of a Discord manager's scope). schemas/webservice_schema.yaml:106-110
auth.discord.enabled false Enable Discord OAuth login. schemas/webservice_schema.yaml:122
auth.discord.client_id (none) The Discord application's client id. schemas/webservice_schema.yaml:123
auth.discord.client_secret (none) Inline client secret. Moved into the secret store on the next start and dropped from the file. schemas/webservice_schema.yaml:126
auth.discord.client_secret_key discord_client_secret Name of a key in the bot's secret store. When set it wins over client_secret; omit it and the default key is read. schemas/webservice_schema.yaml:130
auth.discord.member_ttl 60 Seconds a member resolution may be cached when the bot runs without the Server Members Intent (clamped 1–3600). schemas/webservice_schema.yaml:136
auth.breakglass.enabled false Enable the single emergency Admin credential, for the day the identity provider is what broke. schemas/webservice_schema.yaml:143
auth.breakglass.username (none) The emergency account name. schemas/webservice_schema.yaml:144
auth.breakglass.password_hash (none) A PBKDF2 hash, same format as auth.local. schemas/webservice_schema.yaml:145

Source paths are relative to services/webservice/.

Generate a password hash (never store plaintext):

python -m services.webservice.auth.local --hash --username <name> --roles Admin

The Discord client secret is moved into the bot's secret store on the next start, exactly as the bot token is: write it inline once (auth.discord.client_secret) and the service stores it under config/.secret/discord_client_secret.pkl and drops the key from the file. Nothing else is needed — auth.discord.client_secret_key may name another store key, but the default one needs no entry. A value written inline replaces what the store holds, so changing the secret means writing it there and restarting.

To store it by hand instead:

python -c "from core.utils.os import set_password; set_password('discord_client_secret', '<the secret>')"

then either leave auth.discord.client_secret_key out or set it to discord_client_secret.


How to reach the UI

With frontend: true, the console is at the listen/port you set — for the default config, http://localhost:9876/. An anonymous visitor is redirected to the login page; a signed-in visitor without the needed role gets an "access denied" page.

Discord OAuth login

  1. In the Discord developer portal (your application → OAuth2 → Redirects), register exactly:
<auth.public_base_url>/auth/discord/callback

With the default public_base_url that is http://localhost:9876/auth/discord/callback. The URI is built from auth.public_base_url and never from a request header, so a proxy cannot move it.

  1. The console asks for the scopes identify (who signed in) and guilds.members.read (one fallback membership lookup when the bot cannot read the guild's members — see the problems section).

  2. Supply the client secret inline as auth.discord.client_secret; the service moves it into config/.secret/discord_client_secret.pkl on the next start and drops the key from the file. auth.discord.client_secret_key names a different store key if you want one. Enabled with no secret anywhere — or with a store key that does not exist — the service refuses to install the login backend at startup and logs why, rather than starting a login that cannot complete.

A signed-in Discord user's roles come from the running bot's own role model (bot.yaml → roles:), so the console and the bot's commands can never disagree about who is an Admin.

Local username/password login

Enable auth.local, list users and give each the role names it should hold. This is the only login door on a headless (no_discord: true) install.


Who can see what

Roles are the bot's role names from bot.yaml (roles:). The two-cluster-role pair is Admin and DCS Admin (services/webservice/scope.py:90).

Page or control Who
Dashboard (/), Servers (/fleet), Players (/players), Nodes (/nodes), Instances (/instances) Admin sees everything; DCS Admin sees the untagged servers plus those whose managed_by names one of its roles; a manager sees only their own servers (and the nodes/instances that carry them)
Logs page (/logs) and a node's Download log Admin only
A server's own page and its Missions tab Admin, DCS Admin, and any manager — each on the servers in their view
A server's Configuration tab — DCS config and coalition passwords Admin, and a manager for the servers in their scope
A server's Configuration tab — channels Admin only (a manager may not write channels)
Server and player controls (start/stop/restart, kick/ban/mute/message, mission add/remove/load/…) Admin, DCS Admin, and managers — each on the servers in their view
Node controls (restart, shut down, upgrade, take servers offline, bring servers online) Admin only

Managers and scope. A manager is a signed-in identity whose scope holds a server's managed_by value. A manager sees and acts on their own servers only — a server that declares no managed_by is nobody's manager server: it is left out of every page for them, and a crafted request naming it is refused. For a local user the scope is declared in the config (auth.local.users[].scope); for a Discord user it comes from the roles that map to managed_by.

DCS Admin is narrowed by the same list, exactly as it is on Discord: it holds the untagged servers plus the servers whose managed_by names one of its Discord roles, so a server tagged with a role it does not hold is out of its view and refused on a crafted request. If every server is tagged, a DCS Admin holding none of those roles gets an empty view. Only Admin is unscoped.

Node controls are deliberately Admin-only and unscoped: a manager's scope is a set of servers, and taking a whole node out of service must never widen out of it. A local account with a cluster role and no declared scope keeps the whole cluster, as does break-glass — the operator and emergency paths are never narrowed.

What is not gated by this model: the REST API. Its endpoints carry the RestAPI plugin's own authentication (API key / JWT) and are configured in config/plugins/restapi.yaml, not here.


TLS

This service does not terminate TLS. Put a reverse proxy (nginx, caddy, …) in front of it and serve HTTPS there. Two consequences matter:

  • Set session.https_only: true once the console is reached over TLS, and leave session.same_site at lax.
  • If you bind listen to anything other than loopback and do not set https_only, the cookie is derived Secure (session.py:140-169). A browser does not return a Secure cookie over plain HTTP, so the login will appear to succeed and the very next request will be refused. The service logs exactly this warning at startup. The two ways out are the ones you actually have: bind to 127.0.0.1, or terminate TLS in front and set session.https_only: true.

Problems people actually hit

Symptom Cause and fix
"Login seems to work, then the next page is refused" A Secure session cookie served over plain HTTP on a non-loopback bind. Bind to 127.0.0.1, or terminate TLS and set session.https_only: true. (session.py:140-169)
Discord login "fails the first time, works on retry", or every Discord login fails session.same_site is not lax. strict drops the cookie on the OAuth callback. Set it back to lax. (session.py:201-212)
Everyone is signed out after every restart session.secret is unset, so a random key is used per start. Set it to make sessions survive a restart. (session.py:221-224)
A user who lost a role keeps it for a while (or a signed-in page says "console is starting up") With privileged_intents: false, member roles are re-resolved at most every member_ttl (default 60 s). After a restart, signed-in visitors get a page that retries itself for up to 60 s — no sign-in is needed, it resolves on its own. (auth.discord.member_ttl; shell.py:419-490)
The console is not there at all frontend is not true. The default serves the REST API only. (shell.py:75)
The port is already in use Ports must be 1024–65535 and unique per node; the service retries the bind a few times and then logs an error. (core/utils/validators.py:170, service.py:175-188)

A warning about debug

debug: true turns on the API documentation endpoints (/docs, /redoc, /openapi.json) and uvicorn's access log. Those endpoints are reachable only from loopback and private networks (service.py:115-125), but they still lay out your API, and the access log prints the OAuth callback URL. Enable debug only while testing a locally reachable install — do not expose the port to the internet with it on.


Where the bot log lives

The console's log panel, and the node row's Download log, read the bot's own rotating log at logs/dcssb-<node>.log, relative to the bot's working directory (run.py:87). Rotation size and count come from the bot's main.yaml logging block, not from this service.


More

  • I18N.md — translating the console (adding a language, extracting and compiling catalogs).
  • DEVELOPER.md — the design record: the write surface, the confirm tokens, the background-submit path, member resolution, the retryable page. Operator-facing rules are not defined there; it explains how the console is built.
  • core/ACTIONS.md — the action layer the write controls reach.
  • plugins/restapi/README.md — the REST API served on the same port.

Configuration reference

Key Type Description Example
DEFAULT map Web service settings applied to every node. debug: false
listen: 0.0.0.0
port: 9876
frontend: true

DEFAULT

Key Type Description Example
DEFAULT.debug bool Serve the API docs endpoints and uvicorn's access log. false
DEFAULT.listen str Interface the HTTP server binds to. 0.0.0.0
DEFAULT.port int TCP port the service listens on; unique per node. 9876
DEFAULT.frontend bool Install the admin web console; false serves the API only. false
DEFAULT.log_level str Default level filter of the console's log panel. (one of: info, warning, all) info
DEFAULT.dashboard map Live update settings of the read-only dashboard. live: true
refresh_seconds: 2
stream_clients: 16
DEFAULT.dashboard.live bool Push live updates to the dashboard over SSE. true
DEFAULT.dashboard.refresh_seconds int Seconds between re-rendering and pushing changes. (range: min 1, max 60) 2
DEFAULT.dashboard.stream_clients int Most concurrent live streams the console serves. (range: min 1, max 256) 16
DEFAULT.session map Session cookie settings of the admin web UI. secret:
cookie_name: dcssb_session
max_age: 86400
DEFAULT.session.secret str Key that signs the session cookie; unset picks a random one. (range: min 32) ***
DEFAULT.session.cookie_name str Name of the session cookie. dcssb_session
DEFAULT.session.max_age int Session lifetime in seconds. (range: min 60) 86400
DEFAULT.session.https_only bool Set the Secure flag on the session cookie. false
DEFAULT.session.same_site str Cookie SameSite policy; keep 'lax' for OAuth logins. (one of: lax, strict, none) lax
DEFAULT.access map Per-capability role overrides of the console. music.write:
add: [Media Manager]
remove: [DCS Admin]
music.control:
manager: true
DEFAULT.access.<(.+)> map
DEFAULT.access.<(.+)>.add list Roles granted this capability in addition to the declared ones. - Media Manager
DEFAULT.access.<(.+)>.remove list Declared roles that lose this capability on the website. - DCS Admin
DEFAULT.access.<(.+)>.manager bool Whether a managing scope (managed_by) satisfies this capability. true
DEFAULT.sites map One block per public site, keyed by the site's name. root:
slug: ""
branding: {title: Community}
nav: [overview, leaderboard]
group1:
slug: group1
group_role: "5th Guards"
DEFAULT.sites.<(.+)> map
DEFAULT.sites.<(.+)>.slug str URL-safe path segment of the site; the root site's is empty. "group1"
DEFAULT.sites.<(.+)>.group_role text managed_by token this site shows; absent only for the root site. "5th Guards"
DEFAULT.sites.<(.+)>.enabled bool Whether the public site is served. true
DEFAULT.sites.<(.+)>.avatar bool Set by the site's avatar upload; not meant to be edited by hand. true
DEFAULT.sites.<(.+)>.branding map Title, logo and footer of the site. title: Community
logo: config/site/crest.png
DEFAULT.sites.<(.+)>.branding.title str Brand title of the site. "Community"
DEFAULT.sites.<(.+)>.branding.community_name str The community's name, as the hero's greeting uses it. "5th Guards"
DEFAULT.sites.<(.+)>.branding.welcome str One-line welcome text; %(community)s is filled with the community's name. "%(community)s flies the Caucasus on Tuesday nights."
DEFAULT.sites.<(.+)>.branding.mark_side str Side of the hero's headline the mark is drawn on. (one of: left, right) "left"
DEFAULT.sites.<(.+)>.branding.logo str Path to the site's logo image. config/site/crest.png
DEFAULT.sites.<(.+)>.branding.copyright str Deprecated and ignored — the footer carries the fixed attribution. "Community"
DEFAULT.sites.<(.+)>.branding.footer_links list The footer's links, in declaration order. - {label: Imprint, href: "/imprint"}
- {label: Discord, href: "https://discord.gg/example"}
DEFAULT.sites.<(.+)>.branding.footer_links[].label str (required) The words a visitor reads. Imprint
DEFAULT.sites.<(.+)>.branding.footer_links[].href str (required) Where the link leads. /imprint
DEFAULT.sites.<(.+)>.theme map Palette overrides of the site. preset: brass
light: false
DEFAULT.sites.<(.+)>.theme.preset str Id of a shipped palette preset; at most one theme source may be set. "paper"
DEFAULT.sites.<(.+)>.theme.sheet str Leaf name of an uploaded palette sheet in the site's asset folder; served as written. "theme.css"
DEFAULT.sites.<(.+)>.theme.expert str Body of one :root rule of token declarations; at most 8 KB. --accent: #e8b04b;
DEFAULT.sites.<(.+)>.theme.light bool Render the site in the light palette. false
DEFAULT.sites.<(.+)>.nav list Nav page ids the site offers, in order. - overview
- leaderboard
- squadrons
- players
DEFAULT.sites.<(.+)>.tiles list Tile ids the site's overview shows, in order. - active_week
- online_now
DEFAULT.sites.<(.+)>.sections map Which overview sections the site shows; an absent id is on. A section that is off is neither rendered nor read, except the server board — the live band above the sections prints its figures. The hero figure always stays. season: false
squadrons: false
DEFAULT.sites.<(.+)>.sections.community bool The community readouts band of the overview. true
DEFAULT.sites.<(.+)>.sections.season bool The season panel (hours and sorties per week). true
DEFAULT.sites.<(.+)>.sections.standings bool The top-pilots standings table. true
DEFAULT.sites.<(.+)>.sections.aircraft bool The most-flown aircraft panel. true
DEFAULT.sites.<(.+)>.sections.when_we_fly bool The hours-flown-by-hour-of-day panel; shares its row with the aircraft panel. true
DEFAULT.sites.<(.+)>.sections.squadrons bool The squadrons section; needs the CreditSystem plugin. false
DEFAULT.sites.<(.+)>.sections.servers bool The server board of the overview. true
DEFAULT.sites.<(.+)>.metrics list Leaderboard metric ids the site offers; the board opens on the character's first choice among them, else the first one listed. - playtime
- kd_ratio
DEFAULT.sites.<(.+)>.lang str Language the site renders in. "en"
DEFAULT.sites.<(.+)>.character str The kind of community the site is; decides which figures lead and which metric the board opens on. (one of: pvp, pve, pvpve) "pvpve"
DEFAULT.auth map Identity layer of the admin web UI; optional. public_base_url: http://localhost:9876
local:
enabled: true
DEFAULT.auth.public_base_url str Public origin the console is reachable at. http://localhost:9876
DEFAULT.auth.local map Username and password login for the console. enabled: true
users:
- username: specialk
password_hash: pbkdf2_sha256$***
roles: [Admin]
DEFAULT.auth.local.enabled bool Enable username/password login for the console. true
DEFAULT.auth.local.users list Accounts that may sign in with a username and password. - username: specialk
password_hash: pbkdf2_sha256$***
roles: [Admin]
DEFAULT.auth.local.users[].username str Account name of the local console user. specialk
DEFAULT.auth.local.users[].password_hash str PBKDF2 hash of the account's password. pbkdf2_sha256$***
DEFAULT.auth.local.users[].roles list Role names granted to this account, validated at startup. - Admin
DEFAULT.auth.local.users[].scope list managed_by values this account may see and act on. - Server 1
DEFAULT.auth.discord map Discord OAuth login; the second door into the console. enabled: true
client_id: 123456789012345678
client_secret_key: discord_client_secret
DEFAULT.auth.discord.enabled bool Enable Discord OAuth login. true
DEFAULT.auth.discord.client_id int Client id of your Discord application. 123456789012345678
DEFAULT.auth.discord.client_secret str Inline Discord client secret; moved to the secret store at startup. ***
DEFAULT.auth.discord.client_secret_key str Secret store key holding the client secret; wins inline. discord_client_secret
DEFAULT.auth.discord.member_ttl int Seconds a member resolution is cached without the intent. 60
DEFAULT.auth.discord.auto_start bool Send anonymous visitors straight into Discord sign-in. false
DEFAULT.auth.breakglass map Emergency Admin credential for a broken identity provider. enabled: true
username: emergency
password_hash: pbkdf2_sha256$***
DEFAULT.auth.breakglass.enabled bool Enable the emergency Admin credential. false
DEFAULT.auth.breakglass.username str Username of the emergency Admin account. emergency
DEFAULT.auth.breakglass.password_hash str PBKDF2 hash of the emergency password. pbkdf2_sha256$***