Configuration Reference

This page lists every setting of SelfDocHub and explains how they are loaded. You need it when you deploy or tune an instance.

How settings are loaded#

Settings are applied in this order, later sources override earlier ones:

  1. Built-in defaults.
  2. The .env file. Set DOCS_HUB_ENV_FILE in the process environment to use another path.
  3. The YAML config: the file named by DOCS_HUB_CONFIG, or data/config.yaml.

In practice values from .env override the YAML file, and real process environment variables override both. Missing .env and config files are allowed. Durations use Go syntax such as 30m, 8h or 10s.

In the Docker image selfdochub/selfdochub (compose file in the self-doc-hub-image repository), put settings into the .env file next to docker-compose.yml. Only DOCS_HUB_BASE_URL and DOCS_HUB_SESSION_SECRET are required. The image sets DOCS_HUB_DATA_DIR=/data (the docs-hub-data volume) and DOCS_HUB_ADDR=:8080; do not change them. The optional SELFDOCHUB_VERSION variable in .env selects the image tag (see Upgrading and Backups).

Settings#

File key Environment variable Default Description
n/a DOCS_HUB_ENV_FILE .env Dotenv file path. Read only from the process environment.
addr DOCS_HUB_ADDR :8080 HTTP listen address.
base_url DOCS_HUB_BASE_URL http://localhost:8080 External base URL behind a proxy.
data_dir DOCS_HUB_DATA_DIR data Runtime data directory.
history_depth DOCS_HUB_HISTORY_DEPTH 10 Versions kept per service branch and merged snapshots per service. 0 keeps all.
default_language DOCS_HUB_DEFAULT_LANG en Default UI language.
session_timeout DOCS_HUB_SESSION_TIMEOUT 8h Session token lifetime.
remember_me_timeout DOCS_HUB_REMEMBER_ME_TIMEOUT 720h Token lifetime when "Remember me" is checked (password sign-in only).
session_secret DOCS_HUB_SESSION_SECRET development secret Signing secret for session tokens. Also derives the key that encrypts two-factor secrets, SSO client secrets and notification secrets.
max_spec_bytes DOCS_HUB_MAX_SPEC_BYTES 10485760 Maximum accepted specification size.
search_min_length DOCS_HUB_SEARCH_MIN_LENGTH 3 Minimum query length before the UI sends a search request.
read_timeout DOCS_HUB_READ_TIMEOUT 10s HTTP server read timeout.
write_timeout DOCS_HUB_WRITE_TIMEOUT 10s HTTP server write timeout.
idle_timeout DOCS_HUB_IDLE_TIMEOUT 1m HTTP server idle timeout.
max_concurrent_tryit_requests DOCS_HUB_MAX_CONCURRENT_TRYIT_REQUESTS 1 Highest value of the "Concurrent requests" list in Try-It. 1 hides the list.
max_tryit_response_bytes DOCS_HUB_MAX_TRYIT_RESPONSE_BYTES 4194304 Largest upstream response the Try-It proxy returns. A larger one is answered with 502.
max_tree_depth DOCS_HUB_MAX_TREE_DEPTH 8 Largest number of levels of a service tree. An already deeper saved tree is kept but cannot grow deeper.
notifications_allow_private_targets DOCS_HUB_NOTIFICATIONS_ALLOW_PRIVATE_TARGETS false Allows notification channels to point at loopback, private and link-local addresses.
notifications_max_endpoints DOCS_HUB_NOTIFICATIONS_MAX_ENDPOINTS 5 Endpoints listed per kind of change in a new-version notification.
notifications_license_check_time DOCS_HUB_NOTIFICATIONS_LICENSE_CHECK_TIME 09:00 Daily time (HH:MM, UTC) of the license expiry check.

Warning: Changing session_secret invalidates all session tokens and makes encrypted values unreadable: two-factor secrets (an administrator must reset the authenticators), SSO client secrets and notification channel secrets (they must be entered again).

Data directory#

Everything the application stores is under data_dir (/data in the Docker container, the docs-hub-data volume):

data/
├── config.yaml
├── docs-hub.db         # SQLite database
├── translations/
├── overlays/
├── specs/
└── merged/

Missing directories and seed files are created on first start without overwriting existing files. The SQLite file always lives inside data_dir, so backing up that directory backs up everything. See Upgrading and Backups.

Next steps#

Last updated: