Configuration
3.x Config
Gotify 3.x is configured through environment variables, which can be loaded from an env file. gotify-server.env.example
Example environment variables for the server.
Save as `gotify-server.env` (or export the variables) when edited.
If $GOTIFY_CONFIG_FILE is set, that file is loaded exclusively and none of
the files below are tried. Otherwise the first existing file from the search
order is loaded. Absent or commented out settings fall back to the default
(shown after the =). Variables already exported in the process environment
always take precedence over the loaded file.
Config file search order (used only when $GOTIFY_CONFIG_FILE is unset):
1. gotify-server.env (in the working directory)
2. $XDG_CONFIG_HOME/gotify/gotify-server.env
($XDG_CONFIG_HOME falls back to $HOME/.config when unset)
3. /etc/gotify/server.env
Value types used below:
text a plain string value.
number an integer value.
boolean `true` or `false`.
text-list comma-separated list of strings, parsed as a single CSV line.
A comma can be escaped by wrapping the value in quotes.
Example: a,b,c
Example: "a,b",c -> entries: `a,b` and `c`
json-map a JSON object mapping string keys to string values.
Example: {"X-Foo":"bar","X-Baz":"qux"}
Every variable also supports a "_FILE" suffix that reads the value from a
file at the given path (useful for Docker / Kubernetes secrets), e.g.:
GOTIFY_DEFAULTUSER_PASS_FILE=/run/secrets/admin_pass
GOTIFY_LOGLEVEL ​
# Minimum severity of log messages to emit.
# Values: trace, debug, info, warn, error, fatal, panic
# GOTIFY_LOGLEVEL=info
GOTIFY_SERVER_KEEPALIVEPERIODSECONDS ​
# Interval in seconds between TCP keepalive probes on accepted connections. !! Only change this if you know what you are doing.
#
# Example: 0 uses the Go default (15s)
# Example: -1 disables keepalives entirely.
# Type: number
# GOTIFY_SERVER_KEEPALIVEPERIODSECONDS=0
GOTIFY_SERVER_LISTENADDR ​
# The network address the HTTP server binds to. Leave empty to listen on all
# interfaces (both IPv4 and IPv6). Prefix with "unix:" to listen on a Unix
# domain socket instead of a TCP port.
#
# Type: text
# Example: 192.168.178.2
# Example: unix:/tmp/gotify.sock
# GOTIFY_SERVER_LISTENADDR=
GOTIFY_SERVER_PORT ​
# Port the HTTP server listens on.
# Type: number
# GOTIFY_SERVER_PORT=80
GOTIFY_SERVER_SSL_ENABLED ​
# Enable the HTTPS listener. Requires either CERTFILE+CERTKEY or LETSENCRYPT_ENABLED=true.
# Type: boolean
# GOTIFY_SERVER_SSL_ENABLED=false
GOTIFY_SERVER_SSL_REDIRECTTOHTTPS ​
# Redirect plain HTTP requests to HTTPS. Only effective when SSL_ENABLED=true.
# Type: boolean
# GOTIFY_SERVER_SSL_REDIRECTTOHTTPS=true
GOTIFY_SERVER_SSL_LISTENADDR ​
# The network address the HTTPS server binds to. Leave empty to listen on all
# interfaces (both IPv4 and IPv6). Prefix with "unix:" to listen on a Unix
# domain socket instead of a TCP port.
#
# Type: text
# Example: 192.168.178.2
# Example: unix:/tmp/gotify-ssl.sock
# GOTIFY_SERVER_SSL_LISTENADDR=
GOTIFY_SERVER_SSL_PORT ​
# Port the HTTPS server listens on.
# Type: number
# GOTIFY_SERVER_SSL_PORT=443
GOTIFY_SERVER_SSL_CERTFILE ​
# Path to the TLS certificate.
# Type: text
# Example: /etc/ssl/certs/gotify.crt
# GOTIFY_SERVER_SSL_CERTFILE=
GOTIFY_SERVER_SSL_CERTKEY ​
# Path to the TLS private key.
# Type: text
# Example: /etc/ssl/private/gotify.key
# GOTIFY_SERVER_SSL_CERTKEY=
GOTIFY_SERVER_SSL_LETSENCRYPT_ENABLED ​
# Obtain the TLS certificate automatically from Let's Encrypt.
# Requires SSL_ENABLED=true and LETSENCRYPT_ACCEPTTOS=true.
# Type: boolean
# GOTIFY_SERVER_SSL_LETSENCRYPT_ENABLED=false
GOTIFY_SERVER_SSL_LETSENCRYPT_ACCEPTTOS ​
# Accept the Let's Encrypt Terms of Service.
# Type: boolean
# GOTIFY_SERVER_SSL_LETSENCRYPT_ACCEPTTOS=false
GOTIFY_SERVER_SSL_LETSENCRYPT_CACHE ​
# Directory where issued certificates and ACME account data are persisted. Must
# be writable by the server.
#
# Type: text
# Example: /var/lib/gotify/certs
# GOTIFY_SERVER_SSL_LETSENCRYPT_CACHE=data/certs
GOTIFY_SERVER_SSL_LETSENCRYPT_DIRECTORYURL ​
# Override the ACME directory URL. Leave empty to use the Let's Encrypt
# production server. The staging server has higher rate limits useful for
# testing but issues certificates that are not publicly trusted.
#
# Type: text
# Example: https://acme-staging-v02.api.letsencrypt.org/directory
# GOTIFY_SERVER_SSL_LETSENCRYPT_DIRECTORYURL=
GOTIFY_SERVER_SSL_LETSENCRYPT_HOSTS ​
# Hosts Let's Encrypt should issue certificates for. Each host must resolve
# publicly to this server.
#
# Type: text-list
# Example: mydomain.tld,myotherdomain.tld
# GOTIFY_SERVER_SSL_LETSENCRYPT_HOSTS=
GOTIFY_SERVER_RESPONSEHEADERS ​
# Extra HTTP headers attached to every response.
# Type: json-map
# Example: {"X-Custom-Header":"custom value"}
# GOTIFY_SERVER_RESPONSEHEADERS=
GOTIFY_SERVER_TRUSTEDPROXIES ​
# IPs or CIDR ranges of proxies whose X-Forwarded-For header is trusted to
# determine the real client IP. Include 127.0.0.1 when terminating TLS in a
# sidecar on the same host.
#
# Type: text-list
# Example: 127.0.0.1/32,::1
# GOTIFY_SERVER_TRUSTEDPROXIES=
GOTIFY_SERVER_SECURECOOKIE ​
# Set the Secure flag on session cookies, restricting them to HTTPS
# connections. Enable when the server is reachable over HTTPS.
#
# Type: boolean
# GOTIFY_SERVER_SECURECOOKIE=false
GOTIFY_SERVER_CORS_ALLOWORIGINS ​
# Allowed origins (regex) for cross-origin requests. Setting any CORS_* value
# enables CORS handling.
#
# Type: text-list
# Example: .+\.example\.com,otherdomain\.com
# GOTIFY_SERVER_CORS_ALLOWORIGINS=
GOTIFY_SERVER_CORS_ALLOWMETHODS ​
# HTTP methods permitted in cross-origin requests.
# Type: text-list
# Example: GET,POST
# GOTIFY_SERVER_CORS_ALLOWMETHODS=
GOTIFY_SERVER_CORS_ALLOWHEADERS ​
# Request headers permitted in cross-origin requests.
# Type: text-list
# Example: Authorization,content-type
# GOTIFY_SERVER_CORS_ALLOWHEADERS=
GOTIFY_SERVER_STREAM_PINGPERIODSECONDS ​
# Interval in seconds between WebSocket ping frames sent to streaming clients.
# Only change this if you know what you are doing.
#
# Type: number
# GOTIFY_SERVER_STREAM_PINGPERIODSECONDS=45
GOTIFY_SERVER_STREAM_ALLOWEDORIGINS ​
# Allowed origins (regex) for WebSocket upgrade requests. Same-origin
# connections are always permitted regardless of this setting.
#
# Type: text-list
# Example: .+\.example\.com,otherdomain\.com
# GOTIFY_SERVER_STREAM_ALLOWEDORIGINS=
GOTIFY_OIDC_ENABLED ​
# Enable OpenID Connect Single Sign-On, allowing users to authenticate via an
# external identity provider (e.g. Authelia, Dex, Keycloak). The provider must
# support PKCE (https://oauth.net/2/pkce/); IdPs without PKCE support are
# currently unsupported.
#
# Type: boolean
# GOTIFY_OIDC_ENABLED=false
GOTIFY_OIDC_ISSUER ​
# Base URL of the identity provider. It will be used to discover OIDC endpoints
# via /.well-known/openid-configuration.
#
# Type: text
# Example: https://auth.example.com/realms/myrealm
# GOTIFY_OIDC_ISSUER=
GOTIFY_OIDC_CLIENTID ​
# Client ID registered with the identity provider for this application.
# Type: text
# Example: gotify
# GOTIFY_OIDC_CLIENTID=
GOTIFY_OIDC_CLIENTSECRET ​
# Client secret paired with the client ID.
# Type: text
# Example: super-secret
# GOTIFY_OIDC_CLIENTSECRET=
GOTIFY_OIDC_REDIRECTURL ​
# Callback URL the identity provider redirects to after authentication. Must
# end with `/auth/oidc/callback` and match exactly what is registered at the
# provider. When Gotify is served on a sub-path behind a reverse proxy, include
# it (e.g. https://example.org/gotify/auth/oidc/callback). To support OIDC
# login in the Android app, also register `gotify://oidc/callback` as an
# additional redirect URL at the provider.
#
# Type: text
# Example: https://gotify.example.org/auth/oidc/callback
# GOTIFY_OIDC_REDIRECTURL=
GOTIFY_OIDC_AUTOREGISTER ​
# Automatically create a local user on first OIDC login. When disabled, only
# users that already exist in Gotify can sign in via OIDC.
#
# Type: boolean
# GOTIFY_OIDC_AUTOREGISTER=true
GOTIFY_OIDC_LINK_BY_USERNAME ​
# Bind an OIDC identity to a pre-existing local user with a matching username
# on first login. When disabled (default), existing local users are never
# claimed by an OIDC login and an identity whose username is already taken is
# rejected
#
# Type: boolean
# GOTIFY_OIDC_LINK_BY_USERNAME=false
GOTIFY_OIDC_USERNAMECLAIM ​
# OIDC ID-token claim used as the local username. Common values are
# preferred_username or email.
#
# Type: text
# Example: email
# GOTIFY_OIDC_USERNAMECLAIM=preferred_username
GOTIFY_OIDC_SCOPES ​
# OIDC scopes to request from the identity provider.
# Type: text-list
# GOTIFY_OIDC_SCOPES=openid,profile,email
GOTIFY_DATABASE_DIALECT ​
# Database driver to use. For mysql and postgres the target database must
# already exist and the configured user must have sufficient permissions.
#
# Type: one of sqlite3, mysql, postgres
# GOTIFY_DATABASE_DIALECT=sqlite3
GOTIFY_DATABASE_CONNECTION ​
# Database connection string. Format depends on the dialect.
# Type: text
# Example:
# sqlite3: path/to/database.db
# mysql: gotify:secret@tcp(localhost:3306)/gotifydb?charset=utf8&parseTime=True&loc=Local
# postgres: host=localhost port=5432 user=gotify dbname=gotifydb password=secret
# When using postgres without SSL, append `sslmode=disable` (see https://github.com/gotify/server/issues/90).
# GOTIFY_DATABASE_CONNECTION=data/gotify.db
GOTIFY_DEFAULTUSER_NAME ​
# Username for the initial admin account. Only applied when the database is
# first created; later changes must be made through the WebUI.
#
# Type: text
# Example: myadmin
# GOTIFY_DEFAULTUSER_NAME=admin
GOTIFY_DEFAULTUSER_PASS ​
# Password for the initial admin account. Only applied when the database is
# first created.
#
# Type: text
# Example: super-secret-password
# GOTIFY_DEFAULTUSER_PASS=admin
GOTIFY_PASSSTRENGTH ​
# Bcrypt cost factor for password hashes. Higher values are more secure but slower.
# Type: number
# GOTIFY_PASSSTRENGTH=10
GOTIFY_UPLOADEDIMAGESDIR ​
# Directory where application icons and other uploaded images are stored. Must
# be writable by the server.
#
# Type: text
# Example: /var/lib/gotify/images
# GOTIFY_UPLOADEDIMAGESDIR=data/images
GOTIFY_PLUGINSDIR ​
# Directory scanned for plugin shared libraries on startup. Leave empty to
# disable plugin loading.
#
# Type: text
# Example: /var/lib/gotify/plugins
# GOTIFY_PLUGINSDIR=data/plugins
GOTIFY_REGISTRATION ​
# Allow unauthenticated users to register new user accounts via the public
# registration endpoint.
#
# Type: boolean
# GOTIFY_REGISTRATION=false
NOCOLOR ​
# Disable colored log output. Set to "1" to force-disable colors regardless of
# whether stdout is a terminal. When unset, colors are emitted only if stdout
# is a TTY. See https://no-color.org/.
#
# Type: text
# NOCOLOR=
2.x Config
gotify/server can be configured per config file and environment variables. When using docker it is recommended to use environment variables.
Config File
gotify/server looks in the following paths for config files
- ./config.yml
- /etc/gotify/config.yml
NOTE
When strings contain reserved yml characters then they need to be escaped. A list of reserved characters and how to escape them.
NOTE
The config file /etc/gotify/config.yml can contain sensitive data such as the initial admin password. When using it, you should remove read/write rights from users not owning the file:
$ sudo chmod go-rw /etc/gotify/config.ymlserver:
keepaliveperiodseconds: 0 # 0 = use Go default (15s); -1 = disable keepalive; set the interval in which keepalive packets will be sent. Only change this value if you know what you are doing.
listenaddr: '' # the address to bind on, leave empty to bind on all addresses. Prefix with "unix:" to create a unix socket. Example: "unix:/tmp/gotify.sock".
port: 80 # the port the HTTP server will listen on
ssl:
enabled: false # if https should be enabled
redirecttohttps: true # redirect to https if site is accessed by http
listenaddr: '' # the address to bind on, leave empty to bind on all addresses. Prefix with "unix:" to create a unix socket. Example: "unix:/tmp/gotify.sock".
port: 443 # the https port
certfile: # the cert file (leave empty when using letsencrypt)
certkey: # the cert key (leave empty when using letsencrypt)
letsencrypt:
enabled: false # if the certificate should be requested from letsencrypt
accepttos: false # if you accept the tos from letsencrypt
cache: data/certs # the directory of the cache from letsencrypt
directoryurl: # override the directory url of the ACME server
# Let's Encrypt highly recommend testing against their staging environment before using their production environment.
# Staging server has high rate limits for testing and debugging, issued certificates are not valid
# example: https://acme-staging-v02.api.letsencrypt.org/directory
hosts: # the hosts for which letsencrypt should request certificates
# - mydomain.tld
# - myotherdomain.tld
responseheaders: # response headers are added to every response (default: none)
# X-Custom-Header: "custom value"
trustedproxies: # IPs or IP ranges of trusted proxies. Used to obtain the remote ip via the X-Forwarded-For header. (configure 127.0.0.1 to trust sockets)
# - 127.0.0.1/32
# - ::1
securecookie: false # If the secure flag should be set on cookies. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#secure
cors: # Sets cors headers only when needed and provides support for multiple allowed origins. Overrides Access-Control-* Headers in response headers.
alloworigins:
# - ".+.example.com"
# - "otherdomain.com"
allowmethods:
# - "GET"
# - "POST"
allowheaders:
# - "Authorization"
# - "content-type"
stream:
pingperiodseconds: 45 # the interval in which websocket pings will be sent. Only change this value if you know what you are doing.
allowedorigins: # allowed origins for websocket connections (same origin is always allowed)
# - ".+.example.com"
# - "otherdomain.com"
oidc:
enabled: false # Enable OpenID Connect login, allowing users to authenticate via an external identity provider (e.g. Keycloak, Authelia, Google).
issuer: # The OIDC issuer URL. This is the base URL of your identity provider, used to discover endpoints. Example: "https://auth.example.com/realms/myrealm"
clientid: # The client ID registered with your identity provider for this application.
clientsecret: # The client secret for the registered client.
redirecturl: http://gotify.example.org/auth/oidc/callback # The callback URL that the identity provider redirects to after authentication. Must match exactly what is configured in your identity provider.
autoregister: true # If true, automatically create a new user on first OIDC login. If false, only existing users can log in via OIDC.
usernameclaim: preferred_username # The OIDC claim used to determine the username. Common values: "preferred_username" or "email".
database: # for database see (configure database section)
dialect: sqlite3
connection: data/gotify.db
defaultuser: # on database creation, gotify creates an admin user (these values will only be used for the first start, if you want to edit the user after the first start use the WebUI)
name: admin # the username of the default user
pass: admin # the password of the default user
passstrength: 10 # the bcrypt password strength (higher = better but also slower)
uploadedimagesdir: data/images # the directory for storing uploaded images
pluginsdir: data/plugins # the directory where plugin resides (leave empty to disable plugins)
registration: false # enable registrationsYou can download an example config like this:
$ wget -O config.yml https://raw.githubusercontent.com/gotify/server/master/config.example.ymlNote: the example config doesn't only contain default values.
Database
| Dialect | Connection |
|---|---|
| sqlite3 | path/to/database.db |
| mysql | gotify:secret@tcp(localhost:3306)/gotifydb?charset=utf8&parseTime=True&loc=Local |
| postgres | host=localhost port=5432 user=gotify dbname=gotifydb password=secret |
When using postgres without SSL then sslmode=disable must be added to the connection string. See #90.
For
mysqlandpostgres: Make sure the defined database exists and the user has sufficient permissions.
Environment Variables
Strings in list or map environment settings (f.ex. GOTIFY_SERVER_RESPONSEHEADERS and GOTIFY_SERVER_SSL_LETSENCRYPT_HOSTS) need to be escaped. A list of reserved characters and how to escape them.
See yml config documentation.
GOTIFY_SERVER_PORT=80
GOTIFY_SERVER_KEEPALIVEPERIODSECONDS=0
GOTIFY_SERVER_LISTENADDR=
GOTIFY_SERVER_SSL_ENABLED=false
GOTIFY_SERVER_SSL_REDIRECTTOHTTPS=true
GOTIFY_SERVER_SSL_LISTENADDR=
GOTIFY_SERVER_SSL_PORT=443
GOTIFY_SERVER_SSL_CERTFILE=
GOTIFY_SERVER_SSL_CERTKEY=
GOTIFY_SERVER_SSL_LETSENCRYPT_ENABLED=false
GOTIFY_SERVER_SSL_LETSENCRYPT_ACCEPTTOS=false
GOTIFY_SERVER_SSL_LETSENCRYPT_CACHE=data/certs
GOTIFY_SERVER_SSL_LETSENCRYPT_DIRECTORYURL=
# GOTIFY_SERVER_SSL_LETSENCRYPT_HOSTS=[mydomain.tld, myotherdomain.tld]
# GOTIFY_SERVER_RESPONSEHEADERS={X-Custom-Header: "custom value", x-other: value}
# GOTIFY_SERVER_TRUSTEDPROXIES=[127.0.0.1,192.168.178.2/24]
# GOTIFY_SERVER_CORS_ALLOWORIGINS=[.+\.example\.com, otherdomain\.com]
# GOTIFY_SERVER_CORS_ALLOWMETHODS=[GET, POST]
# GOTIFY_SERVER_CORS_ALLOWHEADERS=[X-Gotify-Key, Authorization]
# GOTIFY_SERVER_STREAM_ALLOWEDORIGINS=[.+.example\.com, otherdomain\.com]
GOTIFY_SERVER_STREAM_PINGPERIODSECONDS=45
GOTIFY_SERVER_SECURECOOKIE=false
GOTIFY_DATABASE_DIALECT=sqlite3
GOTIFY_DATABASE_CONNECTION=data/gotify.db
GOTIFY_DEFAULTUSER_NAME=admin
GOTIFY_DEFAULTUSER_PASS=admin
GOTIFY_PASSSTRENGTH=10
GOTIFY_UPLOADEDIMAGESDIR=data/images
GOTIFY_PLUGINSDIR=data/plugins
GOTIFY_REGISTRATION=false
GOTIFY_OIDC_ENABLED=false
GOTIFY_OIDC_ISSUER=
GOTIFY_OIDC_CLIENTID=
GOTIFY_OIDC_CLIENTSECRET=
GOTIFY_OIDC_REDIRECTURL=http://gotify.example.org/auth/oidc/callback
GOTIFY_OIDC_AUTOREGISTER=true
GOTIFY_OIDC_USERNAMECLAIM=preferred_username