2019-06-27 18:04:06 +00:00
Configuration
=============
You can configure the app by copying `config.sample.json` to
`config.json` and customising it:
2020-07-28 13:59:01 +00:00
For a good example, see https://develop.element.io/config.json.
2019-06-27 18:04:06 +00:00
1. `default_server_config` sets the default homeserver and identity server URL for
2020-07-17 11:22:38 +00:00
Element to use. The object is the same as returned by [https://<server_name>/.well-known/matrix/client ](https://matrix.org/docs/spec/client_server/latest.html#get-well-known-matrix-client ),
2019-06-27 18:04:06 +00:00
with added support for a `server_name` under the `m.homeserver` section to display
a custom homeserver name. Alternatively, the config can contain a `default_server_name`
2020-07-17 11:22:38 +00:00
instead which is where Element will go to get that same object, although this option is
2019-06-27 18:04:06 +00:00
deprecated - see the `.well-known` link above for more information on using this option.
Note that the `default_server_name` is used to get a complete server configuration
whereas the `server_name` in the `default_server_config` is for display purposes only.
* *Note*: The URLs can also be individually specified as `default_hs_url` and
`default_is_url` , however these are deprecated. They are maintained for backwards
compatibility with older configurations. `default_is_url` is respected only
if `default_hs_url` is used.
2020-07-17 11:22:38 +00:00
* Element will fail to load if a mix of `default_server_config` , `default_server_name` , or
2019-06-27 18:04:06 +00:00
`default_hs_url` is specified. When multiple sources are specified, it is unclear
which should take priority and therefore the application cannot continue.
2020-07-17 11:22:38 +00:00
* As of Element 1.4.0, identity servers are optional. See [Identity servers ](#identity-servers ) below.
2021-10-21 14:35:05 +00:00
1. `sso_redirect_options` : Optionally defines how Element will behave with a server which supports
Single Sign On (SSO). By default, Element will do nothing special and simply show a button where
needed for the user to click to navigate to the SSO system. This behaviour can be tuned with the
config options below (as properties of the `sso_redirect_options` object). None of the options apply
if Element thinks the user is already logged in, and similarly Element will assume the default server
supports SSO if these redirect options are used.
* `immediate` : When `true` (default `false` ), Element will automatically redirect all unauthenticated
users to the SSO system to log in regardless of how they reached the app. This overrides the use of
other redirect options.
* `on_welcome_page` : When `true` (default `false` ), Element will automatically redirect all unauthenticated
users to the SSO to log in if the user lands on the welcome page or no specific page. For example,
https://app.element.io/#/welcome and https://app.element.io would redirect if set up to use this option.
This can be useful to maintain guest experience until an account is needed.
2020-08-17 20:02:19 +00:00
1. `features` : Lookup of optional features that may be force-enabled (`true`) or force-disabled (`false`).
When features are not listed here, their defaults will be used, and users can turn them on/off if `showLabsSettings`
2021-04-07 01:39:26 +00:00
allows them to. The available optional experimental features vary from release to release and are
2020-08-17 20:02:19 +00:00
[documented ](labs.md ). The feature flag process is [documented ](feature-flags.md ) as well.
1. `showLabsSettings` : Shows the "labs" tab of user settings. Useful to allow users to turn on experimental features
they might not otherwise have access to.
2019-06-27 18:04:06 +00:00
1. `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.
1. `branding` : Configures various branding and logo details, such as:
1. `welcomeBackgroundUrl` : An image to use as a wallpaper outside the app
2020-04-17 10:31:49 +00:00
during authentication flows. If an array is passed, an image is chosen randomly for each visit.
2019-06-27 18:04:06 +00:00
1. `authHeaderLogoUrl` : An logo image that is shown in the header during
authentication flows
1. `authFooterLinks` : a list of links to show in the authentication page footer:
`[{"text": "Link text", "url": "https://link.target"}, {"text": "Other link", ...}]`
2020-01-22 14:18:26 +00:00
1. `reportEvent` : Configures the dialog for reporting content to the homeserver
admin.
1. `adminMessageMD` : An extra message to show on the reporting dialog to
mention homeserver-specific policies. Accepts Markdown.
2019-06-27 18:04:06 +00:00
1. `integrations_ui_url` : URL to the web interface for the integrations server. The integrations
2020-07-17 11:22:38 +00:00
server is not Element and normally not your homeserver either. The integration server settings
2019-06-27 18:04:06 +00:00
may be left blank to disable integrations.
1. `integrations_rest_url` : URL to the REST interface for the integrations server.
1. `integrations_widgets_urls` : list of URLs to the REST interface for the widget integrations server.
1. `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
2020-09-18 04:22:11 +00:00
"Send Logs" within the application. Bug reports can be disabled/hidden by leaving the
2019-06-27 18:04:06 +00:00
`bug_report_endpoint_url` out of your config file.
1. `roomDirectory` : config for the public room directory. This section is optional.
1. `roomDirectory.servers` : List of other homeservers' directories to include in the drop
down list. Optional.
1. `default_theme` : name of theme to use by default (e.g. 'light')
1. `update_base_url` (electron app only): HTTPS URL to a web server to download
updates from. This should be the path to the directory containing `macos`
and `win32` (for update packages, not installer packages).
1. `piwik` : Analytics can be disabled by setting `piwik: false` or by leaving the piwik config
option out of your config file. If you want to enable analytics, set `piwik` to be an object
containing the following properties:
1. `url` : The URL of the Piwik instance to use for collecting analytics
1. `whitelistedHSUrls` : a list of HS URLs to not redact from the analytics
1. `whitelistedISUrls` : a list of IS URLs to not redact from the analytics
1. `siteId` : The Piwik Site ID to use when sending analytics to the Piwik server configured above
1. `welcomeUserId` : the user ID of a bot to invite whenever users register that can give them a tour
2020-07-17 11:22:38 +00:00
1. `embeddedPages` : Configures the pages displayed in portions of Element that
2019-06-27 18:04:06 +00:00
embed static files, such as:
1. `welcomeUrl` : Initial content shown on the outside of the app when not
2020-07-17 11:22:38 +00:00
logged in. Defaults to `welcome.html` supplied with Element.
2019-06-27 18:04:06 +00:00
1. `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.
2021-02-16 22:19:21 +00:00
1. `loginForWelcome` : Overrides `welcomeUrl` to make the welcome page be the
2021-04-07 01:39:26 +00:00
same page as the login page when `true` . This effectively disables the
2021-02-16 22:19:21 +00:00
welcome page.
2019-06-27 18:04:06 +00:00
1. `defaultCountryCode` : The ISO 3166 alpha2 country code to use when showing
country selectors, like the phone number input on the registration page.
Defaults to `GB` if the given code is unknown or not provided.
2019-10-02 07:04:36 +00:00
1. `settingDefaults` : Defaults for settings that support the `config` level,
as an object mapping setting name to value (note that the "theme" setting
is special cased to the `default_theme` in the config file).
2019-09-12 15:04:24 +00:00
1. `disable_custom_urls` : disallow the user to change the
default homeserver when signing up or logging in.
2020-07-17 11:22:38 +00:00
1. `permalinkPrefix` : Used to change the URL that Element generates permalinks with.
2019-09-30 19:05:15 +00:00
By default, this is "https://matrix.to" to generate matrix.to (spec) permalinks.
2021-01-20 21:39:01 +00:00
Set this to your Element instance URL if you run an unfederated server (eg:
"https://element.example.org").
2020-04-03 19:25:33 +00:00
1. `jitsi` : Used to change the default conference options. Learn more about the
Jitsi options at [jitsi.md ](./jitsi.md ).
2020-03-18 21:47:56 +00:00
1. `preferredDomain` : The domain name of the preferred Jitsi instance. Defaults
2022-01-11 16:15:17 +00:00
to `meet.element.io` . This is used whenever a user clicks on the voice/video
2020-03-18 21:47:56 +00:00
call buttons - integration managers may use a different domain.
2022-01-27 09:44:59 +00:00
This setting is ignored if your homeserver provides
`/.well-known/matrix/client` in its well-known location, and the JSON file
at that location has a key `m.vector.riot.jitsi` . In this case, the
configuration found in the well-known location is used instead.
2020-04-18 17:34:45 +00:00
1. `enable_presence_by_hs_url` : The property key should be the URL of the homeserver
and its value defines whether to enable/disable the presence status display
2020-06-03 12:59:34 +00:00
from that homeserver. If no options are configured, presence is shown for all
2020-04-18 17:34:45 +00:00
homeservers.
1. `disable_guests` : Disables guest access tokens and auto-guest registrations.
Defaults to false (guests are allowed).
1. `disable_login_language_selector` : Disables the login language selector. Defaults
to false (language selector is shown).
1. `disable_3pid_login` : Disables 3rd party identity options on login and registration form
Defaults to false (3rd party identity options are shown).
1. `default_federate` : Default option for room federation when creating a room
2020-04-21 15:27:03 +00:00
Defaults to true (room federation enabled).
2020-09-18 18:24:06 +00:00
1. `desktopBuilds` : Used to alter promotional links to the desktop app. By default
the builds are considered available and accessible from https://element.io. This
config option is typically used in the context of encouraging encrypted message
search capabilities (Seshat). All the options listed below are required if this
option is specified.
1. `available` : When false, the desktop app will not be promoted to the user.
1. `logo` : An HTTP URL to the avatar for the desktop build. Should be 24x24, ideally
an SVG.
1. `url` : An HTTP URL for where to send the user to download the desktop build.
2021-04-09 00:39:09 +00:00
1. `mobileBuilds` : Used to alter promotional links to the mobile app. By default the
builds are considered available and accessible from https://element.io. This config
option is typically used in a context of encouraging the user to try the mobile app
2021-04-12 20:59:56 +00:00
instead of a mobile/incompatible browser.
1. `ios` : The URL to the iOS build. If `null` , it will be assumed to be not available.
If not set, the default element.io builds will be used.
1. `android` : The URL to the Android build. If `null` , it will be assumed to be not available.
If not set, the default element.io builds will be used.
1. `fdroid` : The URL to the FDroid build. If `null` , it will be assumed to be not available.
If not set, the default element.io builds will be used.
2021-01-28 17:28:49 +00:00
1. `mobileGuideToast` : Whether to show a toast a startup which nudges users on
iOS and Android towards the native mobile apps. The toast redirects to the
mobile guide if they accept. Defaults to false.
2021-03-04 18:00:55 +00:00
1. `audioStreamUrl` : If supplied, show an option on Jitsi widgets to stream
audio using Jitsi's live streaming feature. This option is experimental and
may be removed at any time without notice.
2021-04-27 18:34:21 +00:00
1. `voip` : Behaviour related to calls
1. `obeyAssertedIdentity` : If set, MSC3086 asserted identity messages sent
on VoIP calls will cause the call to appear in the room corresponding to the
asserted identity. This *must* only be set in trusted environments.
2021-08-04 09:32:45 +00:00
1. `posthog` : [Posthog ](https://posthog.com/ ) integration config. If not set, Posthog analytics are disabled.
1. `projectApiKey` : The Posthog project API key
2. `apiHost` : The Posthog API host
2021-08-18 08:01:29 +00:00
1. `sentry` : [Sentry ](https://sentry.io/ ) configuration for rageshake data being sent to sentry.
1. `dsn` : the Sentry [DSN ](https://docs.sentry.io/product/sentry-basics/dsn-explainer/ )
2. `environment` : (optional) The [Environment ](https://docs.sentry.io/product/sentry-basics/environments/ ) to pass to sentry
2022-01-21 14:34:47 +00:00
1. `map_style_url` : Map tile server style URL for location sharing. e.g.
'https://api.maptiler.com/maps/streets/style.json?key=YOUR_KEY_GOES_HERE'
2022-01-27 09:44:59 +00:00
This setting is ignored if your homeserver provides
`/.well-known/matrix/client` in its well-known location, and the JSON file
at that location has a key `m.tile_server` (or the unstable version
`org.matrix.msc3488.tile_server` ). In this case, the configuration found in
the well-known location is used instead.
2021-12-06 00:42:19 +00:00
1. `analyticsOwner` : The entity that analytics data is being sent to. Used in copy
when explaining to the user where data is being sent. If not set, defaults to `brand` .
2019-06-27 18:04:06 +00:00
Note that `index.html` also has an og:image meta tag that is set to an image
2020-07-17 11:22:38 +00:00
hosted on riot.im. This is the image used if links to your copy of Element
appear in some websites like Facebook, and indeed Element itself. This has to be
2019-06-27 18:04:06 +00:00
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
2020-07-17 11:22:38 +00:00
it, you can build Element, but run
2019-06-27 18:04:06 +00:00
`RIOT_OG_IMAGE_URL="http://example.com/logo.png" yarn build` .
Alternatively, you can edit the `og:image` meta tag in `index.html` directly
2020-07-17 11:22:38 +00:00
each time you download a new version of Element.
2019-06-27 18:04:06 +00:00
2019-10-28 16:57:22 +00:00
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.
2020-07-17 11:22:38 +00:00
As of Element 1.4.0, all identity server functions are optional and you are
2019-10-28 17:56:38 +00:00
prompted to agree to terms before data is sent to the identity server.
2019-10-28 16:57:22 +00:00
2020-07-17 11:22:38 +00:00
Element will check multiple sources when looking for an identity server to use in
2019-10-28 16:57:22 +00:00
the following order of preference:
1. 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.
2. The identity server provided by the `.well-known` lookup that occurred at
login
3. The identity server provided by the Riot config file
2020-07-17 11:22:38 +00:00
If none of these sources have an identity server set, then Element will prompt the
2019-10-28 16:57:22 +00:00
user to set an identity server first when attempting to use features that
require one.
2020-05-06 10:32:13 +00:00
Currently, the only two public identity servers are https://vector.im and
2019-10-28 16:57:22 +00:00
https://matrix.org, however in the future identity servers will be
decentralised.
2019-06-27 18:04:06 +00:00
Desktop app configuration
=========================
2020-11-25 17:01:19 +00:00
See https://github.com/vector-im/element-desktop#user-specified-configjson
2020-09-15 04:28:57 +00:00
UI Features
===========
Parts of the UI can be disabled using UI features. These are settings which appear
under `settingDefaults` and can only be `true` (default) or `false` . When `false` ,
parts of the UI relating to that feature will be disabled regardless of the user's
preferences.
Currently, the following UI feature flags are supported:
2020-09-18 04:22:11 +00:00
* `UIFeature.urlPreviews` - Whether URL previews are enabled across the entire application.
* `UIFeature.feedback` - Whether prompts to supply feedback are shown.
* `UIFeature.voip` - Whether or not VoIP is shown readily to the user. When disabled,
Jitsi widgets will still work though they cannot easily be added.
* `UIFeature.widgets` - Whether or not widgets will be shown.
* `UIFeature.flair` - Whether or not community flair is shown in rooms.
* `UIFeature.communities` - Whether or not to show any UI related to communities. Implicitly
disables `UIFeature.flair` when disabled.
* `UIFeature.advancedSettings` - Whether or not sections titled "advanced" in room and
user settings are shown to the user.
* `UIFeature.shareQrCode` - Whether or not the QR code on the share room/event dialog
is shown.
* `UIFeature.shareSocial` - Whether or not the social icons on the share room/event dialog
are shown.
* `UIFeature.identityServer` - Whether or not functionality requiring an identity server
is shown. When disabled, the user will not be able to interact with the identity
server (sharing email addresses, 3PID invites, etc).
* `UIFeature.thirdPartyId` - Whether or not UI relating to third party identifiers (3PIDs)
is shown. Typically this is considered "contact information" on the homeserver, and is
not directly related to the identity server.
* `UIFeature.registration` - Whether or not the registration page is accessible. Typically
useful if accounts are managed externally.
* `UIFeature.passwordReset` - Whether or not the password reset page is accessible. Typically
useful if accounts are managed externally.
* `UIFeature.deactivate` - Whether or not the deactivate account button is accessible. Typically
useful if accounts are managed externally.
2020-09-18 18:24:06 +00:00
* `UIFeature.advancedEncryption` - Whether or not advanced encryption options are shown to the
user.
2020-10-28 01:23:06 +00:00
* `UIFeature.roomHistorySettings` - Whether or not the room history settings are shown to the user.
This should only be used if the room history visibility options are managed by the server.
2021-12-21 09:08:35 +00:00
* `UIFeature.TimelineEnableRelativeDates` - Display relative date separators (eg: 'Today', 'Yesterday') in the timeline for recent messages. When false day dates will be used.
