diff --git a/README.md b/README.md index a975d62..44b8bd9 100644 --- a/README.md +++ b/README.md @@ -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