Gotify Server

Gotify can be configured using environment variables. You can save these in a file named gotify-server.env in your working directory, or export them directly to your shell.

Configuration Loading Order

If the $GOTIFY_CONFIG_FILE environment variable is set, Gotify loads that file exclusively. If it is unset, Gotify searches for configuration files in this order:

1. gotify-server.env (in the working directory)
2. $XDG_CONFIG_HOME/gotify/gotify-server.env (defaults to $HOME/.config/gotify/gotify-server.env)
3. /etc/gotify/server.env

Note: Variables already exported in the process environment always take precedence over values loaded from these files.

Value Types

• text: A plain string.
• number: An integer.
• boolean: true or false.
• text-list: A comma-separated list (e.g., a,b,c). Use quotes to include commas in a single entry (e.g., "a,b",c).
• json-map: A JSON object mapping strings to strings (e.g., {"X-Foo":"bar"}).

Secret Management

Every variable supports a _FILE suffix to read the value from a file path. This is recommended for Docker or Kubernetes secrets. Example: GOTIFY_DEFAULTUSER_PASS_FILE=/run/secrets/admin_pass

To create a Gotify plugin, you must implement the plugin.Plugin interface and provide a factory function named NewGotifyPluginInstance.

Key requirements:

1. GetGotifyPluginInfo() plugin.Info: An exported function that returns metadata about the plugin, including its Name, Description, and ModulePath.
2. NewGotifyPluginInstance(ctx plugin.UserContext) plugin.Plugin: An exported factory function that initializes and returns a new instance of your plugin implementation for a specific user context.
3. plugin.Plugin Interface: Your plugin struct must implement:
   • Enable() error: Logic to start the plugin's background tasks or services.
   • Disable() error: Logic to gracefully shut down the plugin.
   • SetMessageHandler(h plugin.MessageHandler): A method to receive the message handler provided by the Gotify server, allowing the plugin to send messages.

Note: The main function should not contain logic; the resulting binary is intended to be loaded as a Go plugin.

import (
	"github.com/gotify/plugin-api"
)

// 1. Provide metadata
func GetGotifyPluginInfo() plugin.Info {
	return plugin.Info{
		Name:        "clock",
		Description: "Sends an hourly reminder",
		ModulePath:  "github.com/gotify/server/v2/example/clock",
	}
}

// 2. Implement the Plugin interface
type Plugin struct {
	msgHandler  plugin.MessageHandler
	enabled     bool
	cronHandler *cron.Cron
}

func (c *Plugin) Enable() error {
	// Start background tasks
	return nil
}

func (c *Plugin) Disable() error {
	// Stop background tasks
	return nil
}

func (c *Plugin) SetMessageHandler(h plugin.MessageHandler) {
	c.msgHandler = h
}

// 3. Provide the factory function
func NewGotifyPluginInstance(ctx plugin.UserContext) plugin.Plugin {
	return &Plugin{}
}

Enable Single Sign-On via an external identity provider (e.g., Authelia, Dex, Keycloak). The provider must support PKCE.

GOTIFY_OIDC_ENABLED=false
GOTIFY_OIDC_ISSUER=https://auth.example.com/realms/myrealm
GOTIFY_OIDC_CLIENTID=gotify
GOTIFY_OIDC_CLIENTSECRET=super-secret
GOTIFY_OIDC_REDIRECTURL=https://gotify.example.org/auth/oidc/callback
GOTIFY_OIDC_AUTOREGISTER=true
GOTIFY_OIDC_USERNAMECLAIM=preferred_username
GOTIFY_OIDC_SCOPES=openid,profile,email

Use these variables to define how the Gotify server listens for connections.

GOTIFY_SERVER_LISTENADDR=192.168.178.2
GOTIFY_SERVER_PORT=80
GOTIFY_SERVER_SSL_ENABLED=false
GOTIFY_SERVER_SSL_REDIRECTTOHTTPS=true

Gotify can automatically obtain and manage TLS certificates via Let's Encrypt. This requires GOTIFY_SERVER_SSL_ENABLED=true and GOTIFY_SERVER_SSL_LETSENCRYPT_ACCEPTTOS=true.

GOTIFY_SERVER_SSL_LETSENCRYPT_ENABLED=false
GOTIFY_SERVER_SSL_LETSENCRYPT_ACCEPTTOS=false
GOTIFY_SERVER_SSL_LETSENCRYPT_CACHE=data/certs
GOTIFY_SERVER_SSL_LETSENCRYPT_HOSTS=mydomain.tld,myotherdomain.tld

Control cross-origin requests and WebSocket behavior.

CORS (Cross-Origin Resource Sharing)

WebSockets

GOTIFY_SERVER_CORS_ALLOWORIGINS=.+\.example\.com,otherdomain\.com
GOTIFY_SERVER_CORS_ALLOWMETHODS=GET,POST
GOTIFY_SERVER_CORS_ALLOWHEADERS=Authorization,content-type
GOTIFY_SERVER_STREAM_PINGPERIODSECONDS=45