Skip to content

CONFIGURATION.md

Latest commit

 

History

History
294 lines (234 loc) · 31.9 KB

CONFIGURATION.md

File metadata and controls

294 lines (234 loc) · 31.9 KB

Configuration

Thunderdome may be configured through environment variables or via a yaml file config.yaml located in one of:

  • /etc/thunderdome/
  • $HOME/.config/thunderdome/
  • Current working directory

Table of Contents

Example yaml configuration file

http:
  domain: thunderdome.dev
db:
  host: localhost
  port: 5432
  user: thor
  pass: odinson
  name: thunderdome

Required configuration items

For Thunderdome to work correctly the following configuration items are required:

Option Environment Variable Description Default Value
http.domain APP_DOMAIN The domain/base URL for this instance of Thunderdome. Used for functional cookies (guest and registered user sessions), WebSocket origin check, and creating URLs in emails. thunderdome.dev
http.cookie_hashkey COOKIE_HASHKEY Secret used to make secure cookies secure. strongest-avenger
config.aes_hashkey CONFIG_AES_HASHKEY Secret used to encrypt passcode fields (e.g. Game JoinCode, LeaderCode). therevengers

Database configuration

Thunderdome uses a Postgres (13 is the minimum required version) database to store all data, the following configuration options exist:

Option Environment Variable Description Default Value
db.host DB_HOST Database host name. db
db.port DB_PORT Database port number. 5432
db.user DB_USER Database user id. thor
db.pass DB_PASS Database user password. odinson
db.name DB_NAME Database instance name. thunderdome
db.sslmode DB_SSLMODE Database SSL Mode (disable, allow, prefer, require, verify-ca, verify-full). disable
db.max_open_conns DB_MAX_OPEN_CONNS Max open db connections 25
db.max_idle_conns DB_MAX_IDLE_CONNS Max idle db connections in pool 25
db.conn_max_lifetime DB_CONN_MAX_LIFETIME DB Connection max lifetime in minutes 5

SMTP (Mail) server configuration

Thunderdome sends emails for user registration related activities, the following configuration options exist:

Option Environment Variable Description Default Value
smtp.enabled SMTP_ENABLED Whether or not sending emails (e.g. welcome, forgot password) is enabled true
smtp.host SMTP_HOST Smtp server hostname. localhost
smtp.port SMTP_PORT Smtp server port number. 25
smtp.user SMTP_USER Smtp server user.
smtp.pass SMTP_PASS Smtp server password.
smtp.secure SMTP_SECURE Set to authenticate with the Smtp server. true
smtp.auth SMTP_AUTH Auth method to use for smtp server PLAIN
smtp.skip_tls_verify SMTP_SKIP_TLS_VERIFY Set to true to skip TLS verification false
smtp.sender SMTP_SENDER From address in emails sent by Thunderdome. no-reply@thunderdome.dev

Configure Admin Email

To grant Admin access to Thunderdome for the first Admin user create an account first, then set the ADMIN_EMAIL environment variable or admin.email config file value. Upon the app starting up Thunderdome will read this value and set that user as ADMIN role.

Authentication Configuration

Thunderdome supports multiple authentication methods though only one primary authentication method can be selected.

Basic Configuration

  • Option: auth.method
  • Environment Variable: AUTH_METHOD
  • Default Value: normal
  • Possible Values: normal, header, ldap, oidc
  • Description: Specifies which authentication method to use for Thunderdome.

Authentication Types

Normal Authentication

  • Type: normal
  • Description: Built-in username/password authentication system
  • Use Case: Standard authentication for most deployments
  • Configuration: Default option, requires no additional setup

Note: Additionally support for Google OAuth alongside the internal auth is available when normal authentication is enabled. See the Google OAuth section below for more details.

Header Authentication

  • Type: header
  • Description: Authentication based on HTTP headers
  • Use Case: Integration with proxy services or systems that authenticate via headers
  • Configuration: Requires additional header configuration (see header auth section)

LDAP Authentication

  • Type: ldap
  • Description: Lightweight Directory Access Protocol integration
  • Use Case: Enterprise environments using directory services
  • Configuration: Requires LDAP server configuration (see LDAP auth section)

OpenID Connect Authentication

  • Type: oidc
  • Description: Single sign-on using OpenID Connect OAuth2 providers
  • Use Case: Integration with identity providers like KeyCloak, Authentik, OneLogin, etc.
  • Configuration: Requires OpenID Connect OAuth2 provider configuration (see OpenID Connect OAuth2 auth section)

Note: OpenID Connect providers that don't implement discovery or host the discovery document at a non-spec complaint path (such as requiring a URL parameter) are not yet supported.

OpenID Connect OAuth2 Configuration

If auth.method is set to oidc, then the Create Account function is disabled and authentication is done using the configured OpenID Connect provider.

Option Environment Variable Description Default Value
auth.oidc.provider_name AUTH_OIDC_PROVIDER_NAME OpenID Connect OAuth2 Provider Name
auth.oidc.provider_url AUTH_OIDC_PROVIDER_URL OpenID Connect OAuth2 Provider URL
auth.oidc.client_id AUTH_OIDC_CLIENT_ID OpenID Connect OAuth2 Client ID
auth.oidc.client_secret AUTH_OIDC_CLIENT_SECRET OpenID Connect OAuth2 Client Secret
auth.oidc.requested_scopes AUTH_OIDC_REQUESTED_SCOPES OpenID Connect OAuth2 Requested Scopes openid profile email
auth.oidc.requested_id_token_claims AUTH_OIDC_REQUESTED_ID_TOKEN_CLAIMS OpenID Connect OAuth2 Requested claims to put into the ID token

The OIDC redirect URI is constructed as /oauth/<auth.oidc.provider_name>/callback which will be added to the end of your normal hosting URL.

LDAP Configuration

If auth.method is set to ldap, then the Create Account function is disabled and authentication is done using LDAP. If the LDAP server authenticates a new user successfully, the Thunderdome user profile is automatically generated.

The following configuration options are specific to the LDAP authentication method:

Option Environment Variable Description
auth.ldap.url AUTH_LDAP_URL URL to LDAP server, typically ldap://host:port
auth.ldap.use_tls AUTH_LDAP_USE_TLS Create a TLS connection after establishing the initial connection.
auth.ldap.bindname AUTH_LDAP_BINDNAME Bind name / bind DN for connecting to LDAP. Leave empty for no authentication.
auth.ldap.bindpass AUTH_LDAP_BINDPASS Password for the bind.
auth.ldap.basedn AUTH_LDAP_BASEDN Base DN for the search for the user.
auth.ldap.filter AUTH_LDAP_FILTER Filter for searching for the user's login id. See below.
auth.ldap.mail_attr AUTH_LDAP_MAIL_ATTR The LDAP property containing the user's emil address.
auth.ldap.cn_attr AUTH_LDAP_CN_ATTR The LDAP property containing the user's name.

The default filter is (&(objectClass=posixAccount)(mail=%s)). The filter must include a %s that will be replaced by the user's login id. The mail_attr configuration option must point to the LDAP attribute containing the user's email address. The default is mail. The cn_attr configuration option must point to the LDAP attribute containing the user's full name. The default is cn.

On Linux, the parameters may be tested on the command line:

ldapsearch -H auth.ldap.url [-Z] -x [-D auth.ldap.bindname -W] -b auth.ldap.basedn 'auth.ldap.filter' dn auth.ldap.mail auth.ldap.cn

The -Z is only used if auth.ldap.use_tls is set, the -D and -W parameter is only used if auth.ldap.bindname is set.

Header auth Configuration

If auth.method is set to header, then the Create Account function is disabled and authentication is done using headers. The assumption being that the only access to thunderdome is via a reverseproxy

The following configuration options are specific to the LDAP authentication method:

Option Environment Variable Default Description
auth.header.usernameHeader AUTH_HEADER_USERNAME_HEADER Remote-User The header to use for the user's username
auth.header.emailHeader AUTH_HEADER_EMAIL_HEADER Remote-Email The header to use for the user's email

Google OAuth

Thunderdome has support for Google OAuth authentication when the auth.method is set to normal and not header or ldap. Google Auth accounts are separate of internal users/password accounts even if they have the same email.

Option Environment Variable Description Default Value
auth.google.enabled AUTH_GOOGLE_ENABLED Google OAuth Enabled false
auth.google.client_id AUTH_GOOGLE_CLIENT_ID Google OAuth Client ID
auth.google.client_secret AUTH_GOOGLE_CLIENT_SECRET Google OAuth Client Secret

HTTP Configuration

Configuring http settings allows for fine-tuning your self-hosted instance of Thunderdome to fit your infrastructure.

Option Environment Variable Description Default Value
http.port PORT Which port to listen for HTTP connections. 8080
http.path_prefix PATH_PREFIX Prefix added to all application urls for shared domain use, in format of /{prefix} e.g. /thunderdome
http.secure_protocol HTTP_SECURE_PROTOCOL Whether app is accessed through HTTPS, used in OAUTH2 redirects true
http.secure_cookie COOKIE_SECURE Use secure cookies or not. true
http.backend_cookie_name BACKEND_COOKIE_NAME The name of the backend cookie utilized for actual auth/validation warriorId
http.frontend_cookie_name FRONTEND_COOKIE_NAME The name of the cookie utilized by the UI (purely for convenience not auth) warrior
http.auth_state_cookie_name HTTP_AUTH_STATE_COOKIE_NAME The name of the cookie utilized by the by auth state validation authState
http.write_timeout HTTP_WRITE_TIMEOUT HTTP response write timeout in seconds 5
http.read_timeout HTTP_READ_TIMEOUT HTTP request read timeout in seconds 5
http.idle_timeout HTTP_IDLE_TIMEOUT HTTP request idle timeout in seconds 30
http.read_header_timeout HTTP_READ_HEADER_TIMEOUT HTTP read header timeout in seconds 2
http.websocket_write_wait_sec HTTP_WEBSOCKET_WRITE_WAIT_SEC Time allowed to write a message to the peer for Websocket connections 10
http.websocket_pong_wait_sec HTTP_WEBSOCKET_PONG_WAIT_SEC Time allowed to read the next pong message from the peer for Websocket connections 60
http.websocket_ping_period_sec HTTP_WEBSOCKET_PING_PERIOD_SEC Send pings to peer with this period for Websocket connections. Must be less than pongWait. 54

Open Telemetry Tracing

Thunderdome features Open Telemetry tracing to aid in monitoring application performance.

Option Environment Variable Description Default Value
otel.enabled OTEL_ENABLED Whether or not Open Telemetry tracing is enabled false
otel.service_name OTEL_SERVICE_NAME Service name of Thunderdome thunderdome
otel.collector_url OTEL_COLLECTOR_URL Open Telemetry supported tracing tool e.g. Uptrace, DataDog localhost:4317
otel.insecure_mode OTEL_INSECURE_MODE Disables client transport security for the exporter's gRPC connection false

Optional configuration items

The following configuration items have sane defaults however aid in fine tuning your self-hosted instance to fit your needs.

Option Environment Variable Description Default Value
config.allowedPointValues CONFIG_POINTS_ALLOWED List of available point values for creating games. 0, 1/2, 1, 2, 3, 5, 8, 13, 20, 21, 34, 40, 55, 100, ?, ☕️
config.defaultPointValues CONFIG_POINTS_DEFAULT List of default selected points for new games. 1, 2, 3, 5, 8 , 13, ?
config.default_point_average_rounding CONFIG_DEFAULT_POINT_AVERAGE_ROUNDING Default selected rounding method used in calculating the average of voted points (when numeric). Can only be one of ceil, floor, round. ceil
config.show_warrior_rank CONFIG_SHOW_RANK Set to enable an icon showing the rank of a user during game. false
config.avatar_service CONFIG_AVATAR_SERVICE Avatar service used, possible values see next paragraph gravatar
config.toast_timeout CONFIG_TOAST_TIMEOUT Number of milliseconds before notifications are hidden. 1000
config.allow_guests CONFIG_ALLOW_GUESTS Whether or not to allow guest (anonymous) users. true
config.allow_registration CONFIG_ALLOW_REGISTRATION Whether or not to allow user registration (outside Admin). true
config.allow_jira_import CONFIG_ALLOW_JIRA_IMPORT Whether or not to allow import plans from JIRA XML. true
config.allow_csv_import CONFIG_ALLOW_CSV_IMPORT Whether or not to allow import plans from a csv file true
config.default_locale CONFIG_DEFAULT_LOCALE The default locale (language) for the UI en
config.allow_external_api CONFIG_ALLOW_EXTERNAL_API Whether or not to allow External API access true
config.external_api_verify_required CONFIG_EXTERNAL_API_VERIFY_REQUIRED Whether External API access requires user to be email verified true
config.user_apikey_limit CONFIG_USER_APIKEY_LIMIT Limit users number of API keys 5
config.show_active_countries CONFIG_SHOW_ACTIVE_COUNTRIES Whether or not to show active countries on landing page false
config.cleanup_battles_days_old CONFIG_CLEANUP_BATTLES_DAYS_OLD How many days back to clean up old games, e.g. games older than 180 days. Triggered manually by Admins . 180
config.cleanup_retros_days_old CONFIG_CLEANUP_RETROS_DAYS_OLD How many days back to clean up old retros, e.g. retros older than 180 days. Triggered manually by Admins . 180
config.cleanup_storyboards_days_old CONFIG_CLEANUP_STORYBOARDS_DAYS_OLD How many days back to clean up old storyboards, e.g. storyboards older than 180 days. Triggered manually by Admins . 180
config.cleanup_guests_days_old CONFIG_CLEANUP_GUESTS_DAYS_OLD How many days back to clean up old guests, e.g. guests older than 180 days. Triggered manually by Admins. 180
config.organizations_enabled CONFIG_ORGANIZATIONS_ENABLED Whether or not creating organizations (with departments) are enabled true
config.require_teams CONFIG_REQUIRE_TEAMS Whether or not creating games, retros, and storyboards require being associated to a Team false
feature.poker FEATURE_POKER Enable or Disable Agile Story Pointing (Poker) feature true
feature.retro FEATURE_RETRO Enable or Disable Agile Retrospectives feature true
feature.storyboard FEATURE_STORYBOARD Enable or Disable Agile Storyboard feature true

Avatar Service configuration

Use the name from table below to configure a service - if not set, gravatar is used. Each service provides further options which then can be configured by a user on the profile page. Once a service is configured, drop downs with the different sprites become available. The table shows all supported services and their sprites.

The none option displays the user's initials (up to 2 letters) on a colored background. The color is automatically generated based on the user's ID for consistency. It can be used in two ways:

  • As the server-wide CONFIG_AVATAR_SERVICE setting - all users will have initials avatars with no configuration options
  • As a user-selectable option within other avatar services (gravatar, robohash, govatar) - users can choose none from their profile dropdown
Name
goadorable (internal)
image
govatar (internal) male female
image image
gravatar mp identicon monsterid wavatar retro robohash
image image image image image image
robohash set1 set2 set3 set4
image image image image
none
image