Skip to content

Configuration

Dokku Pro reads its configuration from /etc/default/dokku-pro, one key=value pair per line. The service loads these values at startup, so restart it after any change (see General Operating Instructions). A minimal file sets the authentication secrets, root token, and license:

API_JWT_ACCESSSECRET=asdfghjklzxc
API_JWT_REFRESHSECRET=qwertyuiopzxcvbnmas
ROOT_TOKEN=password
LICENSE_KEY=CONTENTS_OF_LICENSE_KEY

The remaining keys are grouped by area below. Each entry lists its type, default, and whether it is required.

General

DATABASE_LOCATION

  • Type: string
  • Default: /var/lib/dokku/data/pro/db
  • Required: no
  • Description: Full path to the Dokku Pro database directory. All parent directories must already exist, or Dokku Pro fails to start.

LOG_TTL

  • Type: int (minutes)
  • Default: 10080 (7 days)
  • Required: no
  • Description: How long to retain log messages.

ACTIVITY_TTL

  • Type: int (minutes)
  • Default: 129600 (90 days)
  • Required: no
  • Description: How long to retain activity records.

API

API_JWT_ACCESSSECRET

  • Type: string
  • Default: empty string
  • Required: yes
  • Description: Secret used to sign short-lived JWT access tokens.

API_JWT_REFRESHSECRET

  • Type: string
  • Default: empty string
  • Required: yes
  • Description: Secret used to sign JWT refresh tokens.

Apps

APPS_FILTER

  • Type: list of strings (comma-delimited)
  • Default: empty list
  • Required: no
  • Since: 1.2
  • Description: Apps to hide from the admin UI and API, for cosmetic reasons.

Auth

ROOT_TOKEN

  • Type: string
  • Default: empty string
  • Required: yes
  • Description: Token used as the password for basic-auth login. When unset, authentication is disabled.

ROOT_USERNAME

  • Type: string
  • Default: root
  • Required: no
  • Since: 1.2
  • Description: Username of the built-in "root" administrator.

Note

If you change this value while team management is enabled, add the new username to the global admin team manually.

Reverse Proxy Authentication

See the Reverse Proxy Authentication feature documentation for the security model and per-proxy setup.

REVERSE_PROXY_AUTH_ENABLED

  • Type: bool
  • Default: false
  • Required: no
  • Since: 1.4.0
  • Description: Whether to trust a reverse proxy to authenticate users via a request header. When disabled, the header is ignored.

REVERSE_PROXY_AUTH_HEADER

  • Type: string
  • Default: X-WEBAUTH-USER
  • Required: no
  • Since: 1.4.0
  • Description: The request header to read the authenticated username from.

REVERSE_PROXY_AUTH_TRUSTED_PROXIES

  • Type: list of strings (comma-delimited)
  • Default: empty list
  • Required: no
  • Since: 1.4.0
  • Description: IP addresses or CIDR ranges of the proxies allowed to set the identity header, matched against the request's immediate peer. A single * trusts any source. When empty, the header is never trusted, so the feature is inert even when enabled.

REVERSE_PROXY_AUTH_AUTO_REGISTRATION

  • Type: bool
  • Default: false
  • Required: no
  • Since: 1.4.0
  • Description: Whether to auto-create a passwordless user the first time an unknown but valid username arrives in the trusted header. When disabled, unknown users are rejected.

REVERSE_PROXY_AUTH_REGISTRATION_TEAM

  • Type: string
  • Default: empty string
  • Required: no
  • Since: 1.4.0
  • Description: A team an auto-registered user is added to as a member at creation. The team must already exist or registration fails. Users are only added on creation, never on subsequent logins.

REVERSE_PROXY_AUTH_STRIP_EMAIL_DOMAIN

  • Type: bool
  • Default: false
  • Required: no
  • Since: 1.4.0
  • Description: Whether to strip a trailing @domain from the header value, mapping an email such as alice@example.com to the username alice. Case is preserved.

License

LICENSE_KEY

  • Type: string
  • Default: empty string
  • Required: no
  • Description: The license key for the service, provided inline.

LICENSE_KEY_FILE

  • Type: string
  • Default: empty string
  • Required: no
  • Description: Path to a file containing the license key. Use this instead of LICENSE_KEY to keep the key out of the environment file.

Server

SERVER_GIT_ENABLED

  • Type: bool
  • Default: true
  • Required: no
  • Since: 1.3.1
  • Description: Whether the built-in Git HTTP server is enabled. When disabled, the git routes are not registered and requests to /@git paths return the standard 404 page without a basic-auth challenge.

SERVER_GIT_PUSH_URL_BASE

  • Type: string
  • Default: empty string
  • Required: no
  • Since: 1.3.1
  • Description: A base URL used to build the git push URL shown for each app, e.g. https://git.example.com/@git. The app name is appended to this value (trailing slashes are stripped) and the result is exposed as the push_url attribute on app objects and shown on the app detail page. Useful when the Git HTTP server is reached through a different hostname or proxy than the dashboard. When empty, the UI derives the push URL from the browser location.

SERVER_LOGIN_MESSAGE

  • Type: string
  • Default: empty string
  • Required: no
  • Since: 1.3.1
  • Description: A plain-text message shown as a banner on the sign-in screen, used to signal site status or tell people how to authenticate. Line breaks are preserved, and the value is served without authentication so the UI can display it before login. When empty, no banner is shown.

SERVER_PUBLIC_URL

  • Type: string
  • Default: https://admin.dokku.me
  • Required: no
  • Description: The base URL, including scheme, at which Dokku Pro is hosted. It is used to construct URLs in the CLI, such as password reset links.

SERVER_READ_TIMEOUT

  • Type: int (seconds)
  • Default: 10
  • Required: no
  • Description: The maximum duration for reading an entire request, including the body. A zero or negative value means no timeout.

SERVER_WRITE_TIMEOUT

  • Type: int (seconds)
  • Default: 20
  • Required: no
  • Description: The maximum duration before timing out writes of the response. It is reset whenever a new request's header is read. Like the read timeout, it does not let handlers make decisions on a per-request basis. A zero or negative value means no timeout.

SERVER_NETWORK

  • Type: string
  • Default: tcp
  • Options: tcp, tcp4, tcp6
  • Required: no
  • Description: The local network address family to listen on.

PORT

  • Type: int
  • Default: 5000
  • Required: no
  • Description: The port to listen on.