Document external service configuration

2026-08-25 12:31:37 +00:00
parent 562611e0ca
commit ff17c46b2c
1 changed files with 73 additions and 0 deletions
@@ -91,6 +91,79 @@ the stored frontend configuration when the backend starts. Other frontend
 settings in MariaDB stay unchanged. Restart the backend after you enable or
 disable a plugin.

+## Configure external connections
+
+The following connections use the public frontend address. The examples use
+`https://hub.example.com`. Replace this address with your frontend address.
+
+### Discord
+
+Create an application in the
+[Discord Developer Portal](https://discord.com/developers/applications). Then,
+configure it as follows:
+
+1. Open **OAuth2** and add this exact redirect URL:
+   `https://hub.example.com/auth/discord/callback`.
+2. Copy the application ID to `discord_client_id` in
+   `config/config.json`.
+3. Create a client secret and copy it to `discord_client_secret`.
+4. Add a bot to the application and copy its token to `discord_bot_token`.
+5. Copy the ID of the Discord server to `discord_guild_id`.
+6. Install the bot in that server.
+
+The callback URL points to the frontend. Do not add `/api` to it. The frontend
+requests the `identify`, `email`, and `role_connections.write` OAuth scopes.
+
+Give the bot only the permissions that your configuration needs. It needs
+access to channels where it sends messages. Give it **Manage Roles** if the Hub
+must change roles. Put the bot role above every role that it must manage. The
+[Discord OAuth2 documentation](https://docs.discord.com/developers/topics/oauth2)
+explains application installation and OAuth2 settings.
+
+The client secret and bot token are secrets. Do not commit
+`config/config.json` or publish these values. Reset a secret or token
+immediately if it becomes public.
+
+### Steam
+
+Get a Steam Web API key from the
+[Steam Web API key page](https://steamcommunity.com/dev/apikey). Use the public
+Hub domain when Steam asks for a domain. Copy the key to `steam_api_key` in
+`config/config.json`.
+
+Steam sign-in uses OpenID. You do not have to register a callback URL with
+Steam. The frontend automatically uses
+`https://hub.example.com/auth/steam/callback`. The backend uses the Web API key
+to read Steam profile information.
+
+### TruckersMP
+
+TruckersMP account connections use the public TruckersMP API. They do not need
+an API key or secret. After you create the initial administrator, open the Hub
+administration interface and set `truckersmp_vtc_id` in the global client
+configuration. Use the numeric ID from your TruckersMP VTC page URL. For
+example, use `12345` for `https://truckersmp.com/vtc/12345`.
+
+A user must connect Steam before the user connects TruckersMP. The backend
+checks that both accounts use the same Steam ID. The `trackers` section in
+`config/config.json` configures telemetry services. It does not configure the
+TruckersMP account connection.
+
+### Registration and required connections
+
+Use `register_methods` in `config/config.json` to select the available
+registration methods. Supported values include `email`, `discord`, and
+`steam`. Use `required_connections` to select the accounts that a user must
+connect. Add `truckersmp` if a TruckersMP connection is mandatory. For example:
+
+```json
+"register_methods": ["discord", "steam"],
+"required_connections": ["discord", "steam", "truckersmp"]
+```
+
+Restart the backend after you change these settings. You do not have to rebuild
+an image for changes in `config/config.json`.
+
 ## Start the deployment

 ```bash