# 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](https://hub.docker.com/r/selfdochub/selfdochub) (compose file in the [self-doc-hub-image](https://github.com/SelfDocHub/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](/documentation/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):

```text
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](/documentation/upgrading-and-backups).

## Next steps

- [Installation](/documentation/installation)
- [Security and Audit](/documentation/audit-and-security)

---
Source: https://selfdochub.com/documentation/configuration
