Skip to content
Documentation
Server
Configuration

Configuration

The server reads a single TOML file, named by the -config flag, by the SCREENSHOTTER_CONFIG environment variable, or config.toml in the working directory. Start from the commented config.example.toml of the repository; this page lists every setting it accepts. Secrets can be kept out of the file: jwt_secret, the OIDC client secret and the database DSN each have an *_env_var variant naming an environment variable to read instead.

Required fields

  • canonical_address: public base URL with its scheme and no trailing slash, e.g. https://screenshots.example.com. Required when OIDC is enabled. When set, a request arriving on another scheme or host is redirected there (301, path and query preserved), unless it carries no_redirect=1 in its query string.
  • server.storage_path: directory where PNGs and thumbnails are stored.
  • db.driver: sqlite or postgres.
  • db.dsn: path of the .sqlite file, or a PostgreSQL connection string. db.dsn_env_var names an environment variable to read it from instead; exactly one of the two must be set.
  • At least one authentication backend, see below.
  • jwt_secret: required when OIDC is enabled. A random string of at least 32 characters, e.g. from openssl rand -hex 32. jwt_secret_env_var reads it from the environment instead.

Authentication backends

Each backend has its own enabled flag. At least one must be enabled; when several are, they are tried in the order Tailscale, proxy auth, OIDC, anonymous, and the first one that identifies the request wins.

Anonymous: every request is one shared user, with no login. For local use or a fully trusted private network only.

[anonymous]
enabled = true
# is_admin = false  # give the anonymous user admin privileges

Tailscale: the identity comes from the Tailscale-User-Login and Tailscale-User-Name headers added by a Tailscale proxy. trusted_proxy must list the address ranges the proxy connects from, otherwise the headers are ignored.

trusted_proxy = ["100.64.0.0/10", "fd7a:115c:a1e0::/48"]

[tailscale]
enabled = true

Proxy auth: the identity comes from Remote-* headers added by a reverse proxy that authenticates users itself (Authelia, oauth2-proxy, …). Also requires trusted_proxy.

trusted_proxy = ["10.0.0.0/8"]

[proxy_auth]
enabled = true
# user_header   = "Remote-User"
# email_header  = "Remote-Email"
# name_header   = "Remote-Name"
# groups_header = "Remote-Groups"

OIDC: the server is an OpenID Connect relying party using the authorization-code flow, with any compliant provider (Google, Keycloak, GitHub through Dex, …). Register <canonical_address>/auth/callback as the redirect URI with the provider.

canonical_address = "https://screenshots.example.com"
jwt_secret        = "…32+ random chars…"

[oidc]
enabled       = true
issuer        = "https://accounts.google.com"
client_id     = "<your-client-id>"
client_secret = "<your-client-secret>"
# client_secret_env_var  = "SCREENSHOTTER_OIDC_CLIENT_SECRET"
# scopes                 = ["openid", "email", "profile"]
# groups_claim           = "groups"
# use_pkce               = false
# require_email_verified = true

By default a login is refused when the ID token’s email_verified claim is missing or false; set require_email_verified = false for a provider that does not emit the claim but is trusted to verify addresses.

Admins 

admin_emails = ["alice@example.com"]
admin_groups = ["screenshotter-admins"]

Admins can list every user and their images, and delete any image. admin_groups is matched against the OIDC groups claim or the proxy groups header.

CORS and extension ID 

[cors]
extension_ids = ["nnipkgjcfgekggpkclhdghbbfnpokdlg"]

Uploads are only accepted from the extension IDs listed here. The default is the ID of the extension published on the Chrome Web Store; add the ID shown at chrome://extensions for an unpacked build. Several IDs can be listed.

Optional settings

  • listen_addr: TCP address to bind. Default: 0.0.0.0:8080.
  • title: name shown in the UI. Default: Screenshotter.
  • log_level: debug, info, warn or error. Default: info.
  • favicon_path: path of a custom favicon, also shown as the site icon in the navbar of the image page (the default icon otherwise).
  • trusted_proxy: address ranges (CIDRs) of the reverse proxies whose forwarding headers are trusted, both for the client address and for the Tailscale and proxy-auth identity headers. Empty by default, in which case the direct TCP peer is used for everything.
  • source_url_schemes: URL schemes accepted for the page a screenshot was taken from. Default: ["http", "https"]. Add file or ftp if your users capture such pages; an empty list disables source URLs. javascript, data and vbscript are always rejected.
  • server.max_upload_mb: maximum upload size. Default: 4.
  • server.assets_path: directory of static assets. When set, /favicon.ico is served from it unless favicon_path overrides it.
  • server.require_auth_to_view: when true, viewing an image requires a login. Default: false (anyone with the link can view it).
  • id.length: length of the random image ID. Default: 8, minimum 4.
  • session.ttl: hard session expiry. Default: 168h (7 days).
  • session.renewal_delay: minimum age of a session before it is silently renewed on an authenticated request. Default: 1h.
  • home.cols: maximum number of thumbnail columns in the gallery (1 to 10). Default: 5.
  • home.page_size: screenshots per gallery page. Default: 20.
  • ratelimit.requests_per_second: requests per source IP per second on the public image routes. Default: 6; 0 disables the limit.
  • ratelimit.requests_per_minute: same, per minute. Default: 60; 0 disables the limit.
Deployment