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
-
Create the configuration file
config/services/webservice.yamlwith aDEFAULT:block. The service is switched on by the file: the loader readsconfig/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. -
Set
frontend: trueif 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). -
Configure a login (
auth:) and a session secret (session:) if you use the console. Without anauth: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
- 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.
-
The console asks for the scopes
identify(who signed in) andguilds.members.read(one fallback membership lookup when the bot cannot read the guild's members — see the problems section). -
Supply the client secret inline as
auth.discord.client_secret; the service moves it intoconfig/.secret/discord_client_secret.pklon the next start and drops the key from the file.auth.discord.client_secret_keynames 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: trueonce the console is reached over TLS, and leavesession.same_siteatlax. - If you bind
listento anything other than loopback and do not sethttps_only, the cookie is derivedSecure(session.py:140-169). A browser does not return aSecurecookie 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 to127.0.0.1, or terminate TLS in front and setsession.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 |
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 |
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: |
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: |
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: |
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 |
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"} |
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 |
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 |
DEFAULT.sites.<(.+)>.tiles |
list | Tile ids the site's overview shows, in order. | - active_week |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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$*** |