nodecg.json

Schema

Default Config

Authentication Options

Twitch Authentication Setup

Discord Authentication Setup

Configuration Files Menu

Next: nodecg-core.json

Schema

baseURL String The URL of your instance. By default, this is set to localhost:9092 but you'll need to change this to an online URL if you're hosting your instance online.
host String The IP address or hostname that NodeCG should bind to. Leaving this at 0.0.0.0 will bind NodeCG to your local computer.
port Integer The port that NodeCG should listen on.
exitOnUncaught Boolean Whether or not NodeCG should exit if an uncaught error is encountered.
login Object Contains login settings:
- enabled Boolean Whether login security is enabled.
- sessionSecret String The secret used to salt sessions. This option is required when login.enabled = true and you should set this to something random; do not leave this as the default.
- forceHttpsReturn Boolean Forces Steam & Twitch login return URLs to use HTTPS instead of HTTP.
- local Object Contains local username and password login settings:
  - enabled Boolean Whether local login security is enabled.
  - allowsUsers Array of objects Which usernames and passwords to allow. Example: {"username": "admin", "password": "stuk123"}. This option is required when login.local.enabled = true.
- twitch Object Contains Twitch login settings. See Twitch Authentication Setup for details.
  - enabled Boolean Whether to enable Twitch authentication.
  - clientID String A Twitch application ClientID. This option is required when login.twitch.enabled = true.
  - clientSecret String A Twitch application ClientSecret. This option is required when login.twitch.enabled = true.
  - scope String A space-separated string of Twitch application permissions. Leave this as the default user_read as no other Twitch permissions are required.
  - allowedUsernames Array of strings Which Twitch usernames (all lowercase) to allow. Either this option or allowedIds is required when login.twitch.enabled = true.
  - allowedIds Array of strings Which Twitch IDs to allow. Can be obtained from https://twitchinsights.net/checkuser. Either this option or allowedUsernames is required when login.twitch.enabled = true.
- discord Object Contains Discord login settings. See Discord Authentication Setup for details.
  - enabled Boolean Whether to enable Discord authentication.
  - clientID String A Discord application ClientID. This option is required when login.discord.enabled = true.
  - clientSecret String A Discord application ClientSecret. This option is required when login.discord.enabled = true.
  - scope String A space-separated string of Discord application permissions. identify allows for identification of users, whilst guilds allows identification of servers.
  - allowedUserIDs Array of strings Which Discord IDs to allow. Either this option or allowedGuilds is required when login.discord.enabled = true.
  - allowedGuilds Array of objects Which servers to allow users from. Either this option or allowedUserIDs is required when login.discord.enabled = true. Object formatting:
    - guildID String Discord server ID to allow users from
    - allowedRoleIDs Array of strings Optionally add permitted Role IDs from the allowed server
    - guildBotToken String Discord bot token, needed if allowedRoleIDs is used.

Default Config

{

"baseURL": "localhost:9092",

"host": "0.0.0.0",

"port": 9092,

"exitOnUncaught": true,

"login": {

"enabled": false,

"sessionSecret": "123456789",

"forceHttpsReturn": true,

"local": {

"enabled": false,

"allowedUsers": [{

"username": "username",

"password": "password"

}]

"twitch": {

"enabled": false,

"clientID": "",

"clientSecret": "",

"scope": "user_read",

"allowedUsernames": [""],

"allowedIds": [""]

"discord": {

"enabled": false,

"clientID": "discordClientID",

"clientSecret": "discordClientSecret",

"scope": "identify guilds",

"allowedUserIDs": [],

"allowedGuilds": [{

"guildID": "discordServerID",

"allowedRoleIDs": ["discordRoleID"],

"guildBotToken": "discordBotID"

}]

}

Authentication Options

If you're hosting your NodeCG instance online or on an accessible network, you should enable one or more forms of login authentication. Hosting an unsecured instance is unsafe and could make your system vulnerable. NodeCG doesn't support varying levels of authorization, you either have access to everything or access to nothing. Login status is retained between sessions, once a user logs in, they won't need to log in again until either they manually logout, or their authorization is revoked.

If login is enabled, in addition to the login options you configure, NodeCG will generate a key URL query parameter for each user. This means that instead of logging in, adding this key as a query to the end of a URL will grant access. This is used by OBS to access your instance's graphics without the need to log in. These keys should be kept secret. If a key gets leaked, the user of the key should reset their key using the top-right "Settings" menu on the NodeCG dashboard.

If you're only hosting your NodeCG instance on your local computer and other users are accessing it via Parsec or a similar remote desktop application, you likely won't need to enable any authentication.

Enabling Twitch, Discord or Local login settings will produce these options when first loading the instance. You can enable any combination of the three.

Each user will be assigned a unique key that can be used as a URL query parameter. When copying a graphic URL from the dashboard, it will include this key for pasting the URL into OBS.

If a user's key is compromised they should reset their key in the top-right settings menu. Keys should be kept secret.

Twitch Authentication Setup

Twitch authentication allows your users to log in to the platform through their Twitch account. NodeCG will need access to a Twitch extension and you'll provide a list of authorised usernames or IDs.

Set login.twitch.enabled to true in the config file.
Register a new Application on your Twitch Developers Console. If you've already set up an Application for enabling Twitch Integration, you can edit that application instead.
Give it a suitable name and set the OAuth Redirect URL to https://{YOUR_DEPLOYMENT_URL_HERE}/login/auth/twitch:
- If testing locally, this will be http://localhost:9092/login/auth/twitch
- If you're editing your existing application simply add this URL as an additional Redirect URL
Set the category as 'Broadcaster Suite' and Client Type as 'Confidential'
Copy your Client ID and paste it into the login.twitch.clientID entry in the config file.
Create a New Secret, and copy and paste it into the login.twitch.clientSecret entry in the config file.
Save your Twitch application.
Add Twitch usernames (all lowercase) you wish to authorize as comma-separated strings to login.twitch.allowedUsernames and/or add Twitch IDs you wish to authorize as comma-separated strings to login.twitch.allowedIds.

Discord Authentication Setup

Discord authentication allows your users to log in to the platform through their Discord account. Discord authentication includes three options:

authorize individual users (can be combined with either of the other two options)
authorize all users of a server
only authorize users of a server with a given role

The advantage of the latter two is that authorization can be granted to a server or a server role without the need to authorize individual users. Once you've set it up, any user that joins your server or is granted the set role, will automatically gain authorization.

Set login.discord.enabled to true in the config file.
Create a new Application on your Discord Developers Portal.
Give it a suitable name and add your marathon's logo as the App Icon. Both will be visible to users when they are logging in, so this reassures them they're using the correct application. Save your changes.
Copy your Application ID and paste it into the login.discord.clientID entry in the config file.
Go to the "OAuth2" menu, reset your secret, then copy and paste it into the login.discord.clientSecret entry in the config file.
Set the Redirect URI to https://{YOUR_DEPLOYMENT_URL_HERE}/login/auth/discord. If testing locally, this will be http://localhost:9092/login/auth/discord. Save your changes.
To view user/server/role IDs you'll need to enable developer mode on Discord, which can be found in User Settings > App Settings > Advanced > Developer Mode.
- User: Right-click on a user, select Copy User ID, and paste the ID as a comma-separated string to the login.discord.allowedUserIDs entry in the config file.
- Server: Right-click on your server, select Copy Server ID, and paste the ID to the login.discord.allowedGuilds.guildID entry in the config file.
- Role: Complete the steps for Server authentication. Then:
  1. On your Discord Developers Portal navigate to the Bot menu, create a new bot, and copy and paste the Token to the login.discord.allowedGuilds.guildBotToken entry in the config file.
  2. In a separate browser tab, go to https://discord.com/oauth2/authorize?client_id={YOUR_CLIENT_ID_HERE}&scope=bot&permissions=0 inserting your Client ID. Invite the bot to your server; it will always appear offline which is intended.
  3. On Discord, go to Server Settings > People > Roles, click on the three-dot menu next to the role you want to grant authorization, click Copy Role ID, and paste the ID as a comma-separated string to the login.discord.allowedGuilds.allowedRoleIDs entry in the config file.