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:
- Built-in defaults.
- The
.envfile. SetDOCS_HUB_ENV_FILEin the process environment to use another path. - The YAML config: the file named by
DOCS_HUB_CONFIG, ordata/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_secretinvalidates 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.