8.7 KiB
Configuration
You can configure the app by copying config.sample.json
to
config.json
and customising it:
For a good example, see https://riot.im/develop/config.json.
default_server_config
sets the default homeserver and identity server URL for Riot to use. The object is the same as returned by https://<server_name>/.well-known/matrix/client, with added support for aserver_name
under them.homeserver
section to display a custom homeserver name. Alternatively, the config can contain adefault_server_name
instead which is where Riot will go to get that same object, although this option is deprecated - see the.well-known
link above for more information on using this option. Note that thedefault_server_name
is used to get a complete server configuration whereas theserver_name
in thedefault_server_config
is for display purposes only.- Note: The URLs can also be individually specified as
default_hs_url
anddefault_is_url
, however these are deprecated. They are maintained for backwards compatibility with older configurations.default_is_url
is respected only ifdefault_hs_url
is used. - Riot will fail to load if a mix of
default_server_config
,default_server_name
, ordefault_hs_url
is specified. When multiple sources are specified, it is unclear which should take priority and therefore the application cannot continue. - As of Riot 1.4.0, identity servers are optional. See Identity servers below.
- Note: The URLs can also be individually specified as
features
: Lookup of optional features that may beenable
d,disable
d, or exposed to the user in thelabs
section of settings. The available optional experimental features vary from release to release and are documented. The feature flag process is documented as well.showLabsSettings
: Shows the "labs" tab of user settings even when nofeatures
are enabled or present. Useful for getting at settings which may be otherwise hidden.brand
: String to pass to your homeserver when configuring email notifications, to let the homeserver know what email template to use when talking to you.branding
: Configures various branding and logo details, such as:welcomeBackgroundUrl
: An image to use as a wallpaper outside the app during authentication flowsauthHeaderLogoUrl
: An logo image that is shown in the header during authentication flowsauthFooterLinks
: a list of links to show in the authentication page footer:[{"text": "Link text", "url": "https://link.target"}, {"text": "Other link", ...}]
integrations_ui_url
: URL to the web interface for the integrations server. The integrations server is not Riot and normally not your homeserver either. The integration server settings may be left blank to disable integrations.integrations_rest_url
: URL to the REST interface for the integrations server.integrations_widgets_urls
: list of URLs to the REST interface for the widget integrations server.bug_report_endpoint_url
: endpoint to send bug reports to (must be running a https://github.com/matrix-org/rageshake server). Bug reports are sent when a user clicks "Send Logs" within the application. Bug reports can be disabled by leaving thebug_report_endpoint_url
out of your config file.roomDirectory
: config for the public room directory. This section is optional.roomDirectory.servers
: List of other homeservers' directories to include in the drop down list. Optional.default_theme
: name of theme to use by default (e.g. 'light')update_base_url
(electron app only): HTTPS URL to a web server to download updates from. This should be the path to the directory containingmacos
andwin32
(for update packages, not installer packages).cross_origin_renderer_url
: URL to a static HTML page hosting code to help display encrypted file attachments. This MUST be hosted on a completely separate domain to anything else since it is used to isolate the privileges of file attachments to this domain. Default:https://usercontent.riot.im/v1.html
. This needs to contain v1.html from https://github.com/matrix-org/usercontent/blob/master/v1.htmlpiwik
: Analytics can be disabled by settingpiwik: false
or by leaving the piwik config option out of your config file. If you want to enable analytics, setpiwik
to be an object containing the following properties:url
: The URL of the Piwik instance to use for collecting analyticswhitelistedHSUrls
: a list of HS URLs to not redact from the analyticswhitelistedISUrls
: a list of IS URLs to not redact from the analyticssiteId
: The Piwik Site ID to use when sending analytics to the Piwik server configured above
welcomeUserId
: the user ID of a bot to invite whenever users register that can give them a tourembeddedPages
: Configures the pages displayed in portions of Riot that embed static files, such as:welcomeUrl
: Initial content shown on the outside of the app when not logged in. Defaults towelcome.html
supplied with Riot.homeUrl
: Content shown on the inside of the app when a specific room is not selected. By default, no home page is configured. If one is set, a button to access it will be shown in the top left menu.
defaultCountryCode
: The ISO 3166 alpha2 country code to use when showing country selectors, like the phone number input on the registration page. Defaults toGB
if the given code is unknown or not provided.settingDefaults
: Defaults for settings that support theconfig
level, as an object mapping setting name to value (note that the "theme" setting is special cased to thedefault_theme
in the config file).disable_custom_urls
: disallow the user to change the default homeserver when signing up or logging in.permalinkPrefix
: Used to change the URL that Riot generates permalinks with. By default, this is "https://matrix.to" to generate matrix.to (spec) permalinks. Set this to your Riot instance URL if you run an unfederated server (eg: "https://riot.example.org").
Note that index.html
also has an og:image meta tag that is set to an image
hosted on riot.im. This is the image used if links to your copy of Riot
appear in some websites like Facebook, and indeed Riot itself. This has to be
static in the HTML and an absolute URL (and HTTP rather than HTTPS), so it's
not possible for this to be an option in config.json. If you'd like to change
it, you can build Riot, but run
RIOT_OG_IMAGE_URL="http://example.com/logo.png" yarn build
.
Alternatively, you can edit the og:image
meta tag in index.html
directly
each time you download a new version of Riot.
Identity servers
The identity server is used for inviting other users to a room via third party identifiers like emails and phone numbers. It is not used to store your password or account information.
As of Riot 1.4.0, all identity server functions are optional and you are prompted to agree to terms before data is sent to the identity server.
Riot will check multiple sources when looking for an identity server to use in the following order of preference:
- The identity server set in the user's account data
- For a new user, no value is present in their account data. It is only set if the user visits Settings and manually changes their identity server.
- The identity server provided by the
.well-known
lookup that occurred at login - The identity server provided by the Riot config file
If none of these sources have an identity server set, then Riot will prompt the user to set an identity server first when attempting to use features that require one.
Currently the only two public identity servers are https://vector.im and https://matrix.org, however in the future identity servers will be decentralised.
Desktop app configuration
To run multiple instances of the desktop app for different accounts, you can
launch the executable with the --profile
argument followed by a unique
identifier, e.g riot-web --profile Work
for it to run a separate profile and
not interfere with the default one.
Alternatively, a custom location for the profile data can be specified using the
--profile-dir
flag followed by the desired path.
%APPDATA%\$NAME\config.json
on Windows$XDG_CONFIG_HOME\$NAME\config.json
or~/.config/$NAME/config.json
on Linux~Library/Application Support/$NAME/config.json
on macOS
In the paths above, $NAME
is typically Riot
, unless you use --profile $PROFILE
in which case it becomes Riot-$PROFILE
.