Configuration reference
The server takes all of its configuration from environment variables. The standard compose file
loads them from a .env file via env_file — see
Run the server with Docker for the compose file — so changing
configuration means editing that file on the host and recreating the container.
Two spellings appear below. DOCUCOMMIT_* and SERVER_* keys are the plain environment form. A
few settings have no environment alias and are written as dotted property keys
(docucommit.sync.repos[0].token, spring.mail.host) — the .env file uses Java properties
syntax, so both forms live in the same file. Real OS environment variables take precedence over
anything in .env.
Core
| Variable | Default | What it does |
|---|---|---|
DOCUCOMMIT_LICENSE_KEY | (blank) | Server licence key. Required. While it is blank the server fails closed: /api/, /projects/, and /library/ return 503 license-required. /, /health, /robots.txt, /sitemap.xml, /webhook/, and static assets stay exempt. |
DOCUCOMMIT_WORKDIR | ./var/repos | Directory holding everything the server keeps on disk: each repository clone under <workdir>/<id>, plus .docucommit-license/, .auth/, and .comments/. The standard .env file sets it to /var/repos, matching the docucommit-repos volume mount in the compose file — see Run the server with Docker. |
SERVER_PORT | 8080 | Bind port. Conventionally 8443 when direct TLS is enabled. |
DOCUCOMMIT_LIBRARY_REPO_ID | (blank) | Which repository id is served as the primary library. Blank means the first repository configured. |
Content repositories
At least one repository is required, otherwise the site has nothing to serve. Repositories are
numbered from zero; add _1_, _2_ blocks for more.
Note the licence cap: Pro and Team serve one repository, Enterprise five — see Trial, licences, and seats.
| Variable | Default | What it does |
|---|---|---|
DOCUCOMMIT_SYNC_REPOS_0_ID | (none) | Unique id for this repository. It checks out under <workdir>/<id> and is the {repoId} in the webhook URL. |
DOCUCOMMIT_SYNC_REPOS_0_URL | (none) | Git URL to clone and pull. ssh:// reuses the host’s ~/.ssh keys and known_hosts; https:// and file:/// also work. |
DOCUCOMMIT_SYNC_REPOS_0_BRANCH | (blank) | Branch to track. Blank falls back to the remote’s default branch. |
docucommit.sync.repos[0].username | (blank) | Username for an https:// remote. |
docucommit.sync.repos[0].token | (blank) | Password or access token for an https:// remote. |
docucommit.sync.repos[0].ssh-key | (blank) | Private key to use for this repository instead of the host’s default. Point at the private key, not the .pub file. |
docucommit.sync.repos[0].ssh-passphrase | (blank) | Passphrase for the key above. |
docucommit.sync.repos[0].ssl-verify | true | Set to false to skip TLS certificate verification for this remote. Development only. |
DOCUCOMMIT_SYNC_ON_STARTUP | true | Pull every configured repository once at startup. |
DOCUCOMMIT_SYNC_SCHEDULED | true | Enable the periodic background pull. |
DOCUCOMMIT_SYNC_INTERVAL | 5m | Time between scheduled pulls. Accepts 30s, 5m, 1h. |
For an SSH remote, the host key has to be in known_hosts before the first clone. This is the
same one-time step git itself requires:
ssh-keyscan git.example.com >> ~/.ssh/known_hosts
Use ssh-keyscan -p 29418 gerrit.example.com for a non-standard port. The compose file mounts
~/.ssh read-only, so the file the container reads is the one on the host.
Webhook
The webhook turns a push into an immediate pull instead of waiting for the next scheduled sync. It is host-agnostic: a CI step, or any client that can set a request header, sends it. It is not a stock GitHub webhook signature.
| Variable | Default | What it does |
|---|---|---|
DOCUCOMMIT_WEBHOOK_SECRET | (blank) | Shared secret the caller presents in the X-DocuCommit-Token header. Blank is fail-closed: every request gets 401, so the endpoint is safe to expose before you configure it. |
DOCUCOMMIT_WEBHOOK_ENABLED | true | Documented master switch for the endpoint. In v1.0.1 the secret is the effective gate — clear DOCUCOMMIT_WEBHOOK_SECRET to turn the webhook off. |
DOCUCOMMIT_WEBHOOK_DEBOUNCE | 3s | Trailing debounce. A burst of pushes collapses into a single sync. |
Triggering a sync of the repository whose id is docs:
curl -X POST https://docs.example.com/webhook/sync/docs \
-H "X-DocuCommit-Token: $DOCUCOMMIT_WEBHOOK_SECRET"
A valid call returns 202 with {"status":"accepted","repoId":"docs"}, and the pull happens
after the debounce window. A wrong or missing token returns 401; an id that is not configured
returns 404.
Accounts and sign-in
Sign-in exists for comment attribution and notifications. It never gates reading — every page, search, and export stays available to anyone who can reach the server.
| Variable | Default | What it does |
|---|---|---|
DOCUCOMMIT_USER_STORE | (blank) | Path to the accounts JSON file. Blank means <workdir>/.auth/users.json. |
DOCUCOMMIT_REGISTRATION_ENABLED | true | Whether visitors can create an account themselves. Set to false to freeze the user list. |
docucommit.comments.store | (blank) | Directory holding the comment sidecar files. Blank means <workdir>/.comments. |
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET | (unset) | Google OAuth credentials. |
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET | (unset) | GitHub OAuth credentials. |
The OAuth block in application.yml ships commented out. Uncomment it and supply the credentials
above to enable the buttons. With nothing configured, the sign-in page offers local email and
password only, and the provider buttons are hidden.
Search-engine controls
| Variable | Default | What it does |
|---|---|---|
DOCUCOMMIT_NOINDEX_LIBRARIES | (blank) | Comma-separated library slugs to hide from crawlers. Each becomes a Disallow line in /robots.txt and an X-Robots-Tag: noindex, nofollow header on /library/{slug}/**. Blank means everything is indexable. |
DOCUCOMMIT_NOINDEX_ALL | false | Hide the whole site: X-Robots-Tag: noindex, nofollow on every response, no Sitemap: line, and /sitemap.xml returns 404. For demo and staging instances. |
DOCUCOMMIT_PUBLIC_BASE_URL | (blank) | Canonical public URL — scheme and host, no trailing slash. It builds the absolute URLs in /sitemap.xml and the Sitemap: line in /robots.txt. While it is blank, /sitemap.xml returns 404. |
Email notifications
Email only activates when spring.mail.host is set. Without it, mentions and follows are still
recorded, but nothing is sent.
| Variable | Default | What it does |
|---|---|---|
spring.mail.host | (unset) | SMTP host. Its presence is what switches the sender on. |
spring.mail.port | (unset) | SMTP port. 465 for implicit SSL, 587 for STARTTLS. |
spring.mail.username | (unset) | SMTP username. Also used as the From address, so it must be a mailbox you own. |
spring.mail.password | (unset) | SMTP password. |
spring.mail.properties.mail.smtp.auth | (unset) | Require authentication on the SMTP connection. |
spring.mail.properties.mail.smtp.ssl.enable | (unset) | Implicit SSL. Pair with port 465. |
spring.mail.properties.mail.smtp.starttls.enable | (unset) | STARTTLS. Pair with port 587. |
spring.mail.properties.mail.smtp.starttls.required | (unset) | Refuse to send if STARTTLS is unavailable. |
docucommit.notifications.digest-interval | 15m | How often queued notifications are batched into one digest email. |
docucommit.notifications.base-url | (blank) | Base URL used for the links inside notification emails. |
docucommit.notifications.subscription-store | (blank) | Path to the follow and subscription store. Blank means a sidecar file under <workdir>. |
docucommit.notifications.outbox | (blank) | Path to the notification outbox. Blank means a sidecar file under <workdir>. |
Pick one transport and match it to the port. Mixing implicit SSL with 587 produces a
“bad greeting” connection error rather than a useful message.
TLS
| Variable | Default | What it does |
|---|---|---|
SERVER_SSL_ENABLED | false | Serve HTTPS from the server itself instead of terminating TLS in front of it. |
SERVER_SSL_KEY_STORE | (blank) | Path to the keystore holding the certificate and key. |
SERVER_SSL_KEY_STORE_PASSWORD | (blank) | Keystore password. |
SERVER_SSL_KEY_STORE_TYPE | PKCS12 | Keystore format. |
SERVER_SSL_KEY_ALIAS | (blank) | Alias of the key entry. Blank means the keystore’s only entry. |
Most deployments leave these alone and terminate TLS in front of the server — see Reverse proxy and TLS.
The editor’s configuration
Most editor settings live in the app’s own Settings UI, not environment variables. A handful of environment variables control the editor’s local backend before that UI is reachable:
| Variable | Default | What it does |
|---|---|---|
DOCUCOMMIT_LOCAL_ADDRESS | 127.0.0.1 | Bind address for the editor’s local backend. |
DOCUCOMMIT_LOCAL_PORT | 8081 | Bind port for the editor’s local backend. |
DOCUCOMMIT_LOCAL_SEARCH_TTL | 10s | How often the editor checks whether the search index needs rebuilding. |
DOCUCOMMIT_LOCAL_MAX_UPLOAD | 200MB | Maximum size for a single attachment upload. |
DOCUCOMMIT_UPDATE_CHECK_ENABLED | true | Whether the editor’s Java backend checks docucommit.se/download/latest.json for a newer release. |