RegisterSign in

Eternaltwin

Home | Applications

Application configuration

Every Eternaltwin game or application must be able to be configured using either environment variables or a configuration file.

This page is about the configuration of your application: a game or a third-party website integrating with Eternaltwin. The configuration of the Eternaltwin server itself is a separate document: Eternaltwin configuration.

Configuration format

Environment variable

When using environment variables, use UPPER_SNAKE_CASE. Prefix all the variables with an identifier unique to your application.

  • Example: NEOPARC_EXTERNAL_URI to configure the external URI of Neoparc (Dinoparc remake).

Configuration file

Do not invent your own file format. Use either .env files, JSON files or TOML files.

Provide an example configuration file in your repository.

Zero configuration

You may allow your application to start without any environment variable or configuration file. Assume that the application is running locally in development mode in such case.

Runtime representation

Your application must fully load the configuration during its initialization.

It must check that the configuration is valid and represent it as a single value. Pick the representation that best suits your language, usually a class instance. Avoid untyped maps.

The goal is to avoid ad-hoc configuration access: the rest of the application should only use this configuration value.

Configurable values

This section lists the values your application must let its operator configure.

Eternaltwin URI

Eternaltwin URI, used for OAuth and the API.

Example values:

  • http://localhost:50320/
  • https://eternaltwin.org/

Eternaltwin OAuth client id

OAuth client_id for Eternaltwin.

Example values:

  • eternalfest@clients
  • d19e61a3-83d3-410f-84ec-49aaab841559

Eternaltwin OAuth client secret

OAuth client_secret for Eternaltwin. It is the secret field of your app's section in the Eternaltwin server's eternaltwin.toml.

Example values:

  • dev_secret
  • 8tbuCjaBVkL2HZDh7cH2m2Fdv3CSEgK8

Eternaltwin OAuth scopes

The permissions your application requests, sent as the scope parameter of the authorization request. The value is a space-separated list of scope tokens:

  • base: identity only. Always granted; it is also what an authorization request that omits scope asks for.
  • forum:read: read the forum as the user.
  • forum:write: post, reply and edit as the user. Implies forum:read.
  • forum:moderate: use the moderation commands where the user is already a moderator. Implies forum:write.

The forum scopes are a chain, so asking for the widest one you need is enough: forum:write also grants forum:read and base. An unknown token makes the whole request invalid.

Make this configurable rather than hard-coded: the Eternaltwin server caps what your client may ask for through the allowed_scopes key of its registration, and a deployment that was granted less than another must be able to ask for less without a rebuild. Requesting more than the cap is refused.

Example values:

  • base
  • forum:write

See The forum from an application for what each forum scope buys, and Eternaltwin for OAuth for where the parameter goes.

External URI

Public URI for the root of the application.

Example values:

  • http://directquiz.localhost/
  • http://directquiz.eternaltwin.org/