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.

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 =

# Links that are shown in the footer. By default, two links are shown:
#
# ```
# footer_links = ["about", "graphiql"]
# ```
#
# By overwriting this 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",
# ]
# ```
#footer_links =

# 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".
#
# Instead of the manually translated label, you can use some builtin
# labels like this:
#
#     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.
#metadata =

# 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"]
#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 MiiM 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. Compare the authentication docs! Possible values:
#
# - "none": Tobira never reads auth headers and thus, users cannot login
#    at all. Only useful for development and as safe default.
# - "full-auth-proxy": Tobira does no session handling and expects an auth
#   proxy in front of every route, passing user info via auth headers.
# - "login-proxy": Tobira does its own session handling and expects the auth
#    system to send `POST /~session` with auth headers to create a session.
#
# **Important**: in either case, you HAVE to make sure to remove all auth
# headers from incoming user requests before passing them on to Tobira!
#
# 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.
# TODO: describe properties, requirements and usages of username.
#
# 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"

# 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 =


# 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. JWTs are only used to automatically authenticate
# users against Opencast with short-lived tokens. They are not used for
# user sessions.
[auth.jwt]
# Signing algorithm for JWTs. Prefer `ES` style algorithms over others.
# The algorithm choice has to be configured in Opencast as well.
#
# Valid values: "ES256", "ES384"
#
# Required! This value must be specified.
#signing_algorithm =

# Path to the secret signing key. The key has to be PEM encoded.
#
# # For `ES*` algorithms
#
# Has to be an EC key encoded as PKCS#8. To generate such a key, you can
# run the following commands. You can replace `secp256r1` with other
# supported values like `secp384r1`.
#
#     openssl ecparam -name secp256r1 -genkey -noout -out sec1.pem
#     openssl pkcs8 -topk8 -nocrypt -in sec1.pem -out private-key.pem
#
# Here, the `sec1.pem` is encoded as SEC1 instead of PKCS#8. The second
# command converts the key.
#
# Required! This value must be specified.
#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"


[theme]
# Height of the header (containing the logo, search bar, and several
# icons). Increasing this size only enlarges the logo, the other elements
# stay the same size and centered.
#
# Default value: 100
#header_height = 100

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


[theme.logo]

# The normal, usually wide logo that is shown on desktop screens.
[theme.logo.large]
# Path to the image file.
#
# Required! This value must be specified.
#path =

# Resolution of the image. This is used to avoid layout shifts and to
# calculate the correct logo margins. The exact numbers don't matter,
# only the ratio between them does.
#
# Required! This value must be specified.
#resolution =


# A smaller logo (usually close to square) used for small screens, mostly
# on mobile phones.
[theme.logo.small]
# Path to the image file.
#
# Required! This value must be specified.
#path =

# Resolution of the image. This is used to avoid layout shifts and to
# calculate the correct logo margins. The exact numbers don't matter,
# only the ratio between them does.
#
# Required! This value must be specified.
#resolution =


[theme.color]
# Default value: "#347856"
#navigation = "#347856"

# Accent color with large contrast to navigation color.
#
# Default value: "#007A96"
#accent = "#007A96"

# Grey tone with 50% lightness/brightness. Several brighter and
# darker variants of this are created automatically. This is
# configurable in case you want to have a slightly colored grey,
# e.g. slightly warm.
#
# Default value: "#808080"
#grey50 = "#808080"

# A usually red color used to indicate errors, potentially destructive
# actions, and the like.
#
# Default value: "#b64235"
#danger = "#b64235"

# A color for positive things or some "call to action" buttons, like the
# login button. Typically green.
#
# Default value: "#27ae60"
#happy = "#27ae60"