Configuration

Tobira will check for config.toml (in the working directory) and /etc/tobira/config.toml and use the first one it finds. You can set an explicit config path with the environment variable TOBIRA_CONFIG_PATH or the -c CLI flag. If none of these is found, Tobira will exit with an error.

You usually have some additional files that Tobira needs access to (e.g. the logo). All file paths you use in the configuration file are relative to the configuration file itself.

The Tobira binary is able to emit a "configuration template", i.e. the empty structure of the config file without any values set, but with descriptions of all possible options. It's a great starting point to configure your Tobira. You can generate it with ./tobira write-config, but that file is also attached to each release as config.toml. Or you can just copy it from below.

For configuring the [theme] section, see the next chapter.

All configuration options

This is the the configuration template described above:

# Configuration for Tobira.
#
# All relative paths are relative to the location of this configuration file.
# Duration values are specified as string with a unit, e.g. "27s". Valid
# units: 'ms', 's', 'min', 'h' and 'd'.
#
# All user-facing texts you can configure here have to be specified per
# language, with two letter language key. Only English ('en') is required.
# Take `general.site_title` for example:
#
#     [general]
#     site_title.en = "My university"
#     site_title.de = "Meine Universität"
#

[general]
# The main title of the video portal. Used in the HTML `<title>`, as main
# heading on the home page, and potentially more.
#
# Required! This value must be specified.
#site_title =

# Whether or not to show a download button on the video page.
#
# Default value: true
#show_download_button = true

# Links that are shown in the footer.
#
# By overwriting this default value, you can remove the default links and
# add custom ones. Note that these two default links are special and can
# be specified with only the shown string. To add custom ones, you need
# to define a label and a link. Example:
#
# ```
# footer_links = [
#     { label = { en = "Example" }, link = "https://example.com" },
#     "about",
# ]
# ```
#
# Default value: ["about", "graphiql"]
#footer_links = ["about", "graphiql"]

# Additional metadata that is shown below a video. Example:
#
#     [general.metadata]
#     dcterms.spatial = { en = "Location", de = "Ort" }
#     "http://my.domain/xml/namespace".courseLink = { en = "Course", de = "Kurs"}
#
# As you can see, this is a mapping of a metadata location (the XML
# namespace and the name) to a translated label. For the XML namespace
# URL, there is one shortcut: the "http://purl.org/dc/terms/" is
# abbreviated as just "dcterms".
#
# It's likely easier to write this as shown above (as extra section)
# instead of trying to cram it into one line (as shown below with the
# default value).
#
# Instead of the manually translated label, you can use some builtin
# labels like this:
#
#     [general.metadata]
#     dcterms.license = "builtin:license"
#     dcterms.source = "builtin:source"
#
# As soon as you add your own metadata fields, this default is
# overwritten. If you want to keep showing the license and source data,
# you have to add those two lines to your configuration.
#
# Default value: { dcterms = { license = "builtin:license", source = "builtin:source" } }
#metadata = { dcterms = { license = "builtin:license", source = "builtin:source" } }

# A list of URL paths that are reserved for other usages. Users won't be
# able to create top-level realms with those path segments. Tobira also
# has some additional built-in reserved paths (e.g. `/favicon.ico`).
#
# Example: ["/Shibboleth.sso", "/something-else"]
#
# Default value: []
#reserved_paths = []


[db]
# The username of the database user.
#
# Default value: "tobira"
#user = "tobira"

# The password of the database user.
#
# Required! This value must be specified.
#password =

# The host the database server is running on.
#
# Default value: "127.0.0.1"
#host = "127.0.0.1"

# The port the database server is listening on. (Just useful if your
# database server is not running on the default PostgreSQL port).
#
# Default value: 5432
#port = 5432

# The name of the database to use.
#
# Default value: "tobira"
#database = "tobira"

# The TLS mode for the database connection.
#
# - "on": encryption is required and the server certificate is validated
#    against trusted certificates which are loaded from the system's
#    native certificate store. If `server_cert` is set, that's also
#    loaded and trusted.
# - "without-verify-cert": encryption is required, but the server
#   certificate is not checked. Allows MITM attacks! Discouraged.
# - "off": no encryption. Discouraged even more.
#
# Default value: "on"
#tls_mode = "on"

# Path to the server certificate. This makes sense if you don't want to
# install the certificate globally on the system. Has to be a PEM encoded
# file containing one or more X509 certificates.
#server_cert =


[http]
# The TCP port the HTTP server should listen on.
#
# Default value: 3080
#port = 3080

# The bind address to listen on.
#
# Default value: "127.0.0.1"
#address = "127.0.0.1"

# Unix domain socket to listen on. Specifying this will overwrite
# the TCP configuration. Example: "/tmp/tobira.socket".
#unix_socket =

# Unix domain socket file permissions.
#
# Default value: 493
#unix_socket_permissions = 493


[auth]
# The mode of authentication. See the authentication docs for more information.
#
# Default value: "none"
#mode = "none"

# Link of the login button. If not set, the login button internally
# (not via `<a>`, but through JavaScript) links to Tobira's own login page.
#login_link =

# Link of the logout button. If not set, clicking the logout button will
# send a `DELETE` request to `/~session`.
#logout_link =

# The header containing a unique and stable username of the current user.
#
# Default value: "x-tobira-username"
#username_header = "x-tobira-username"

# The header containing the human-readable name of the current user
# (e.g. "Peter Lustig").
#
# Default value: "x-tobira-user-display-name"
#display_name_header = "x-tobira-user-display-name"

# The header containing a comma-separated list of roles of the current user.
#
# Default value: "x-tobira-user-roles"
#roles_header = "x-tobira-user-roles"

# If a user has this role, they are treated as a moderator in Tobira,
# giving them the ability to modify the realm structure among other
# things.
#
# Default value: "ROLE_TOBIRA_MODERATOR"
#moderator_role = "ROLE_TOBIRA_MODERATOR"

# If a user has this role, they are allowed to use the Tobira video
# uploader to ingest videos to Opencast.
#
# Default value: "ROLE_TOBIRA_UPLOAD"
#upload_role = "ROLE_TOBIRA_UPLOAD"

# If a user has this role, they are allowed to use Opencast Studio to
# record and upload videos.
#
# Default value: "ROLE_TOBIRA_STUDIO"
#studio_role = "ROLE_TOBIRA_STUDIO"

# If a user has this role, they are allowed to use the Opencast editor to
# edit videos they have write access to.
#
# Default value: "ROLE_TOBIRA_EDITOR"
#editor_role = "ROLE_TOBIRA_EDITOR"

# If a user has this role, they are allowed to create their own "user realm".
#
# Default value: "ROLE_USER"
#user_realm_role = "ROLE_USER"

# Duration of a Tobira-managed login session.
# Note: This is only relevant if `auth.mode` is `login-proxy`.
#
# Default value: "30d"
#session_duration = "30d"

# A shared secret for **trusted** external applications.
# Send this value as the `x-tobira-trusted-external-key`-header
# to use certain APIs without having to invent a user.
# Note that this should be hard to guess, and kept secret.
# Specifically, you are going to want to encrypt every channel
# this is sent over.
#trusted_external_key =

# Determines whether or not Tobira users are getting pre-authenticated against
# Opencast when they visit external links like the ones to Opencast Studio
# or the Editor. If you have an SSO-solution, you don't need this.
#
# Default value: false
#pre_auth_external_links = false


# Configuration related to the built-in login page.
[auth.login_page]
# Label for the user-ID field. If not set, "User ID" is used.
#user_id_label =

# Label for the password field. If not set, "Password" is used.
#password_label =

# An additional note that is displayed on the login page. If not set, no
# additional note is shown.
#note =


# JWT configuration. See documentation for more information.
[auth.jwt]
# Signing algorithm for JWTs.
#
# Valid values: "ES256", "ES384"
#
# Default value: "ES384"
#signing_algorithm = "ES384"

# Path to the secret signing key. The key has to be PEM encoded. If not
# specified, a key is generated everytime Tobira is started. The randomly
# generated key is fine for most use cases.
#secret_key =

# The duration for which a JWT is valid. JWTs are just used as temporary
# ways to authenticate against Opencast, so they just have to be valid
# until the frontend received the JWT and used it with Opencast.
#
# Default value: "30s"
#expiration_time = "30s"


[log]
# Determines how many messages are logged. Log messages below
# this level are not emitted. Possible values: "trace", "debug",
# "info", "warn", "error" and "off".
#
# Default value: "debug"
#level = "debug"

# If this is set, log messages are also written to this file.
# Example: "/var/log/tobira.log".
#file =

# If this is set to `false`, log messages are not written to stdout.
#
# Default value: true
#stdout = true

# If set to `true`, HTTP header of each incoming request are logged
# (with 'trace' level).
#
# Default value: false
#log_http_headers = false


[opencast]
# URL to Opencast. Currently used for all purposes (syncing, Studio,
# upload, ...) unless overwritten below. In the future, Tobira might use
# the service registry API to figure out suitable nodes for each
# purpose (again, unless explicitly specified below).
#
# Some HTTP requests to Opencast contain the unencrypted `sync.password`,
# so using HTTPS is strongly encouraged. In fact, HTTP is only allowed if
# the host resolves to a loopback address.
#
# Example: "http://localhost:8080" or "https://oc.my-uni.edu".
#host =

# Explicitly set Opencast node used for data synchronization. The Tobira
# module needs to run on this node.
#sync_node =

# Explicitly set Opencast node used for the video uploader. Has to offer
# the ingest API.
#upload_node =

# Explicitly set base-URL to Opencast Studio.
#
# Example: "https://admin.oc.my-uni.edu/studio".
#studio_url =

# Explicitly set the base-URL to the Opencast editor.
#
# Example: "https://admin.oc.my-uni.edu/editor-ui/index.html".
#editor_url =


[sync]
# Username of the user used to communicate with Opencast for data syncing.
# This user has to have access to all events and series. Currently, that
# user has to be admin.
#
# Required! This value must be specified.
#user =

# Password of the user used to communicate with Opencast.
#
# Required! This value must be specified.
#password =

# A rough estimate of how many items (events & series) are transferred in
# each HTTP request while harvesting (syncing) with the Opencast
# instance.
#
# A very large number might cause problems due to the Opencast or Tobira
# node having to hold that many items in memory, or due to network
# request size restrictions. Too small of a number means that the
# overhead of each request will become more significant, slowing down
# harvesting. But more importantly: if your Opencast instance has more
# items with exactly the same `updated` timestamp than the configured
# `preferred_harvest_size`, Tobira is unable to harvest. The `updated`
# timestamp is has millisecond precision, so this situation is highly
# unlikely to occur naturally. However, this can easily occur with
# artificial timestamps, like when you migrate old Opencast data
# (without an `updated` timestamp). Be aware of that.
#
# Default value: 500
#preferred_harvest_size = 500

# The duration to wait after a "no new data" reply from Opencast. Only
# relevant in `--daemon` mode.
#
# Default value: "30s"
#poll_period = "30s"


[meili]
# The access key. This can be the master key, but ideally should be an API
# key that only has the priviliges it needs.
#
# Required! This value must be specified.
#key =

# The host MeiliSearch is running on. As requests include the `key`, you
# should use HTTPS if Meili is running on another machine. In fact, HTTP
# is disallowed unless the host resolves to a loopback address.
#
# Default value: "http://127.0.0.1:7700"
#host = "http://127.0.0.1:7700"

# A prefix for index names in Meili. Useful only to avoid collision if
# other services use Meili as well.
#
# Default value: "tobira_"
#index_prefix = "tobira_"

# How often DB changes are written back to the search index.
#
# Default value: "5s"
#update_interval = "5s"


# See the relevant chapter in our documentation on how to configure this section.
[theme]
# Height of the header. Increasing this size only enlarges the logo, the
# other elements stay the same size and centered.
#
# Default value: 85
#header_height = 85

# Path to an SVG file that is used as favicon.
#
# Required! This value must be specified.
#favicon =


# Logo used in the top left corner of the page. Using SVG logos is recommended.
[theme.logo]
# The normal, usually wide logo that is shown on desktop screens. The
# value is a map with a `path` and `resolution` key:
#
#     large = { path = "logo.svg", resolution = [20, 8] }
#
# The resolution is only an aspect ratio. It is used to avoid layout
# shifts in the frontend by allocating the correct size for the logo
# before the browser loaded the file.
#
# Required! This value must be specified.
#large =

# A less wide logo used for narrow screens.
#small =


# Colors used in the UI. Specified in sRGB.
[theme.color]
# The primary color used for most colored UI elements. Should have a
# perceived brightness (L in LCH color space) of 35-55.
#
# Default value: "#01758f"
#primary = "#01758f"

# A color used to indicate errors and potentially destructive actions.
# Should be red.
#
# Default value: "#b64235"
#danger = "#b64235"

# Grey tone. This is configurable in case you want to have a slightly
# colored grey, e.g. slightly warm.
#
# Only hue and saturation (or more precisely, hue and chroma in the LCH
# color space) are used from this. The brightness of the configured color
# is ignored. Still try using a color with roughly 50% perceived
# brightness to reduce rounding errors.
#
# Default value: "#777777"
#grey50 = "#777777"

# A color for positive things and "call to action" elements. Only specify
# this color if your primary color is reddish!
#happy =


[upload]
# Whether specifying a series is required when uploading.
#
# Default value: false
#require_series = false