You can choose to configure HedgeDoc with either a config file or with environment variables.
Environment variables take precedence over configurations from the config files. They generally start with CMD_ for our own options, but we also list node-specific options you can configure this way.
Environment variables are processed in lib/config/environment.js - so this is the first place to look if anything is missing not obvious from this document. The default values are defined in lib/config/default.js, in case you wonder if you even need to override it.
The config file is processed in lib/config/index.js - so this is the first place to look if anything is missing not obvious from this document. The default values are defined in lib/config/default.js, in case you wonder if you even need to override it. To get started, it is a good idea to take the config.json.example and copy it
to config.json before filling in your own details.
Note:Due to the rename process we renamed all HMD_-prefix variables to be CMD_-prefixed. The old ones continue to work.
HSTS options to use with HTTPS (default is the example value, max age is a year)
CMD_HSTS_ENABLE
true or false
set to enable HSTS if HTTPS is also enabled (default is true)
CMD_HSTS_INCLUDE_SUBDOMAINS
true or false
set to include subdomains in HSTS (default is true)
CMD_HSTS_MAX_AGE
31536000, 60 * 60 * 24 * 365
max duration in seconds to tell clients to keep HSTS status (default is a year)
CMD_HSTS_PRELOAD
true or false
whether to allow preloading of the site's HSTS status (e.g. into browsers)
csp
{"enable": true, "addDefaults": true}
Nested object to configure the Content Security Policy
csp.enable
CMD_CSP_ENABLE
true or false
Whether to apply a Content-Security-Policy header to responses. We don't recommend disabling this option, as it significantly reduces the security of the application.
csp.addDefaults
true or false
Disable to not include the default CSP. Be careful, this will break the application if the correct directives are not set manually.
csp.directives
no default, {"scriptSrc": "trustworthy-scripts.example.com"}
Custom CSP directives. These are passed to Helmet - see their documentation for more information on the format.
csp.addDisqus
CMD_CSP_ADD_DISQUS
false or true
Enable to allow users to add Disqus comments to their notes or presentations. We don't recommend enabling this option, as it increases the attack surface of XSS attacks.
csp.addGoogleAnalytics
CMD_CSP_ADD_GOOGLE_ANALYTICS
false or true
Enable to allow users to add Google Analytics to their notes. We don't recommend enabling this option, as it increases the attack surface of XSS attacks.
csp.upgradeInsecureRequests
auto or true or false
By default (auto), insecure (HTTP) requests are upgraded to HTTPS via CSP if useSSL is on. To change this behaviour, set to either true or false.
Allows to add a URL for CSP reports in case of violations.
csp.allowFraming
CMD_CSP_ALLOW_FRAMING
true or false
Disable to disallow embedding of the instance via iframe. We strongly recommend disabling this option, as it increases the attack surface of XSS attacks.
csp.allowPDFEmbed
CMD_CSP_ALLOW_PDF_EMBED
true or false
Disable to disallow embedding PDFs. We recommend disabling this option, as it increases the attack surface of XSS attacks.
cookiePolicy
CMD_COOKIE_POLICY
lax, strict or none
Set a SameSite policy whether cookies are send from cross-origin. Be careful: setting a SameSite value of none without https breaks the editor.
If allowAnonymous is false: allow users to select freely permission, allowing guests to edit existing notes (default is false).
allowFreeURL
CMD_ALLOW_FREEURL
false or true
Set to allow new note creation by accessing a nonexistent note URL. This is the behavior familiar from Etherpad.
requireFreeURLAuthentication
CMD_REQUIRE_FREEURL_AUTHENTICATION
false or true
Set to require authentication for FreeURL mode style note creation.
defaultPermission
CMD_DEFAULT_PERMISSION
editable, freely, limited, locked, protected or private
Set notes default permission (only applied on signed-in users).
sessionName
connect.sid
Cookie session name.
sessionLife
CMD_SESSION_LIFE
14 * 24 * 60 * 60 * 1000, 1209600000 (14 days)
Cookie session life time in milliseconds.
sessionSecret
CMD_SESSION_SECRET
secret
Cookie session secret used to sign the session cookie. If none is set, one will randomly generated on each startup, meaning all your users will be logged out. Can be generated with e.g. pwgen -s 64 1.
Set to allow registration of new accounts using an email address. If set to false, you can still create accounts using the command line - see bin/manage_users for details (In production mode, remember to run it with NODE_ENV set as production in the enviroment). This setting has no effect if email or CMD_EMAIL is false. The default for allowEmailRegister or CMD_ALLOW_EMAIL_REGISTER is true.
An object detailing your OAuth2 provider. Refer to the Mattermost or Nextcloud examples for more details!
CMD_OAUTH2_USER_PROFILE_URL
no default, https://example.com
Where to retrieve information about a user after successful login. Needs to output JSON. (no default value) Refer to the Mattermost or Nextcloud examples for more details on all of the CMD_OAUTH2... options.
CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR
no default, name
where to find the username in the JSON from the user profile URL. (no default value)
CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR
no default, display-name
where to find the display-name in the JSON from the user profile URL. (no default value)
CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR
no default, email
where to find the email address in the JSON from the user profile URL. (no default value)
CMD_OAUTH2_USER_PROFILE_ID_ATTR
no default, user_uuid
where to find the dedicated user ID (optional, overrides CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR)
CMD_OAUTH2_TOKEN_URL
no default, https://example.com
sometimes called token endpoint, please refer to the documentation of your OAuth2 provider (no default value)
CMD_OAUTH2_AUTHORIZATION_URL
no default, https://example.com
authorization URL of your provider, please refer to the documentation of your OAuth2 provider (no default value)
CMD_OAUTH2_CLIENT_ID
no default, afae02fckafd...
you will get this from your OAuth2 provider when you register HedgeDoc as OAuth2-client, (no default value)
CMD_OAUTH2_CLIENT_SECRET
no default, afae02fckafd...
you will get this from your OAuth2 provider when you register HedgeDoc as OAuth2-client, (no default value)
CMD_OAUTH2_PROVIDERNAME
no default, My institution
Optional name to be displayed at login form indicating the oAuth2 provider
CMD_OAUTH2_SCOPE
no default, openid email profile
Scope to request for OIDC (OpenID Connect) providers.
CMD_OAUTH2_ROLES_CLAIM
no default, roles
ID token claim, which is supposed to provide an array of strings of roles
CMD_OAUTH2_ACCESS_ROLE
no default, role/hedgedoc
The role which should be included in the ID token roles claim to grant access
Info
If you are using a CA not trusted by Node.js (like Let's Encrypt e.g) for your OAuth2 provider you can set the NODE_EXTRA_CA_CERTS environment variable to the CA certificate file path of your CA.
Remember to also make the file available inside the Docker container, if you're running HedgeDoc in Docker container.
These are only relevant when they are also configured in sync with their
CMD_IMAGE_UPLOAD_TYPE. Also keep in mind, that filesystem is available, so
you don't have to use either of these.