CodiMD Configuration

You can configure CodiMD with environment variables or with config file config.json. We recommend you use environment variables to configure CodiMD. config.json reserve for development use only.

All environment variables you can configure are defined in ./lib/config/environment.js and overwrite .config.json.

Image Not Showing Possible Reasons

The image file may be corrupted
The server hosting the image is unavailable
The image path is incorrect
The image format is not supported

Learn More →

Hint: You would find most config options duplicated in both the config file and environment variables.

The rationale behind this architecture design is that we recommend:

using environment variables at any production environment
using the config file config.json when developing

CodiMD Configuration

General

Server Resource URL

Environment Variable	Data Type	Default Value	Example Value	Description
CMD_DOMAIN	`string`		`codimd.example.com`	The domain name your service will be hosted.
CMD_URL_PATH	`string`		`codimd`	The path in a URL your service will be hosted. (e.g., codimd.example.com/`urlpath`)
CMD_URL_ADDPORT	`boolean`	`false`	`true`. `false`	Set to assign port for URL. (You don't need this for ports 80 or 443. This only works when `domain` is set)

Service Listening

Environment Variable	Data Type	Default Value	Example Value	Description
CMD_HOST	`string`	`0.0.0.0`	`127.0.0.1`	The host to which CodiMD will listen.
CMD_PORT	`string`	`3000`	`3000`	The port on which CodiMD will be accessed.
CMD_PATH	`string`		`/var/run/codimd.sock`	Path to the UNIX socket CodiMD will listen to. (If specified, `host` and `port` will be ignored.)

Others

Environment Variable	Data Type	Default Value	Example Value	Description
CMD_USECDN	`boolean`	`true`	`true`. `false`	Set to use CDN resources.
CMD_AUTO_VERSION_CHECK	`boolean`	`true`	`true`. `false`	Specify to check latest CodiMD version automatically

Image Not Showing Possible Reasons

The image file may be corrupted
The server hosting the image is unavailable
The image path is incorrect
The image format is not supported

Learn More →

We do collect running version number and IP address when checking version automatically. Opt-out by setting CMD_AUTO_VERSION_CHECK to false

Environment Variable	Data Type	Example Value	Description
CMD_ALLOW_ORIGIN	`List`	`localhost, example.com`	List of white listed domain names for CORS.

Database

CodiMD supports MySQL and PostgreSQL

Environment Variable	Data Type	Default Value	Example Value	Description
CMD_DB_URL	`string`		`mysql://username:password@database.host.com:9821/database_name`	The URL on which the database is hosted.

Privilege and Privacy

User Privilege

Environment Variable	Data Type	Default Value	Example Value	Description
CMD_ALLOW_ANONYMOUS	`boolean`	`false`	`true`. `false`	Allow anonymous usage.
CMD_ALLOW_ANONYMOUS_EDITS	`boolean`	`false`	`true`. `false`	Allow anonymous guests to edit existing notes that has freely permission (applied only when `allowAnonymous` is True).
CMD_ALLOW_ANONYMOUS_VIEWS	`boolean`	`true`	`true`. `false`	Allow anonymous guests to view existing notes that has editable, locked permission (applied only when `allowAnonymous` is True).
CMD_DEFAULT_PERMISSION	`string`	`editable`	`freely`, `editable`, `limited`, `locked`, `protected` or `private`	Set default permission for new notes. See permission meanings here.

Session

Environment Variable	config.json	Example Value	Description
CMD_SESSION_LIFE	sessionLife	<integer> `14 * 24 * 60 * 60 * 1000`	Session life time in milliseconds.
CMD_SESSION_SECRET	sessionSecret	<string> `1337h4x0r`	Secret used to sign the session cookie. If not set, one will be randomly generated on startup.

User Features

Environment Variable	config.json	Example Value	Description
CMD_ALLOW_GRAVATAR	allowGravatar	<boolean> `true`. `false`	Use gravatar as a default profile picture source.
CMD_ALLOW_FREEURL	allowFreeURL	<boolean> `true`. `false`	Allow new note creation by accessing a nonexistent note URL.
CMD_FORBIDDEN_NODE_IDS	forbiddenNoteIDs	<List> `robots.txt`	When `allowFreeUrl` is enabled, string items in this list will not be auto-created.
CMD_ALLOW_PDF_EXPORT	allowPDFExport	<boolean> `true`. `false`	Allow export to PDF.
CMD_DROPBOX_APPKEY	appKey	<string> `HWiDIfHvTvKj3_zMwA6aSw`	The key for import notes from, or export notes to, Dropbox.
CMD_DEFAULT_USE_HARD_BREAK	defaultUseHardbreak	<boolean> `true`. `false`	Configurable default break style. Default is `true`
CMD_LINKIFY_HEADER_STYLE	linkifyHeaderStyle	<string> `keep-case`, `lower-case`, or `gfm`	Configure the generated link style of heading.

Configuration for header link style

CodiMD supports three different styles of header link. Take 3.1. Good Morning my Friend! - Do you have 5$? this header for example, CodiMD would generate link id as follows:

type	result	description
`keep-case`	`31-Good-Morning-my-Friend---Do-you-have-5`	Default
`lower-case`	`31-good-morning-my-friend---do-you-have-5`
`gfm`	`31-good-morning-my-friend---do-you-have-5`	It works like 'lower-case', but making sure the ID is unique. 1st appearance: `31-good-morning-my-friend---do-you-have-5` 2nd appearance: `31-good-morning-my-friend---do-you-have-5-1` 3rd appearance: `31-good-morning-my-friend---do-you-have-5-2`

PlantUML

CodiMD supports PlantUML out of box, however you can specify your own PlantUML instance:

Environment Variable	config.json	Example Value	Description
CMD_PLANTUML_SERVER	`plantuml.server`	<string> `https://www.plantuml.com/plantuml`	The URL of PlantUML instance

Image Storage

Environment Variable	config.json	Example Value	Description
CMD_IMAGE_UPLOAD_TYPE	imageUploadType	<string> `imgur`, `s3`, `minio`, `azure` or `filesystem`	Where to store user-uploaded images. Default is `filesystem`. The storage is assigned by the config: uploadsPath under Resources.

Imgur

Environment Variable	config.json	Example Value	Description
CMD_IMGUR_CLIENTID	clientID	<string> `CLIENT_ID`	Imgur API client id.

S3

See this guide: store image on S3.

Environment Variable	config.json	Example Value	Description
CMD_S3_ACCESS_KEY_ID	accessKeyId	<string> `HWiDIfHvTvKj3_zMwA6aSw`	AWS access key id.
CMD_S3_SECRET_ACCESS_KEY	secretAccessKey	<string> `HWiDIfHvTvKj3_zMwA6aSw`	AWS secret key.
CMD_S3_REGION	region	<string> `YOUR_S3_REGION`	AWS S3 region.
CMD_S3_BUCKET	s3bucket	<string> `YOUR_S3_BUCKET_NAME`	Bucket name when `imageUploadType` is set to s3 or minio.
CMD_S3_ENDPOINT	endpoint	<string> `s3.example.com`	Custom AWS S3 endpoint.

Minio

See this guide: store image on Minio.

Environment Variable	config.json	Example Value	Description
CMD_MINIO_ACCESS_KEY	accessKey	<string> `HWiDIfHvTvKj3_zMwA6aSw`	Minio access key.
CMD_MINIO_SECRET_KEY	secretKey	<string> `HWiDIfHvTvKj3_zMwA6aSw`	Minio secret key.
CMD_MINIO_ENDPOINT	endpoint	<string> `YOUR_MINIO_HOST`	Minio host (endpoint).
CMD_MINIO_PORT	port	<string> `9000`	Minio port.
CMD_MINIO_SECURE	secure	<boolean> `true`. `false`	Minio secure.

Azure

Environment Variable	config.json	Example Value	Description
CMD_AZURE_CONNECTION_STRING	connectionString	<string> `CONNECTION_STRING`	Azure Blob Storage connection string
CMD_AZURE_CONTAINER	container	<string> `CONTAINER_NAME`	Azure Blob Storage container name (automatically created if nonexistent).

Authentication

Email

Environment Variable	config.json	Example Value	Description
CMD_EMAIL	email	<boolean> `true`. `false`	Allow email sign-in.
CMD_ALLOW_EMAIL_REGISTER	allowEmailRegister	<boolean> `true`. `false`	Allow email registration (only applied when `email` is set.

Image Not Showing Possible Reasons

The image file may be corrupted
The server hosting the image is unavailable
The image path is incorrect
The image format is not supported

Learn More →

Hint: You can always use bin/manage_users:createUser to create users if registration is disabled.

SAML

See this guide: Authenticate with SAML and this example: SAML - OneLogin as example

Environment Variable	config.json	Example Value	Description
CMD_SAML_IDPSSOURL	idpSsoUrl	<string> `https://idp.example.com/sso`	Authentication endpoint of the IdP.
CMD_SAML_IDPCERT	idpCert	<string> `/path/to/cert.pem`	Certificate file path of IdP in PEM format.
CMD_SAML_ISSUER	issuer	<string> `codimd.mydomain.net`	Identity of CodiMD, the service provider (optional, default: serverurl).
CMD_SAML_IDENTIFIERFORMAT	identifierFormat	<string> urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress	Name identifier format (the example format is the default).
CMD_SAML_GROUPATTRIBUTE	groupAttribute	<string> `memberOf`	Attribute name for group list (optional).
CMD_SAML_REQUIREDGROUPS	requiredGroups	<list> `Hackmd-users, admins`	White list groups, users in these groups are allowed access.
CMD_SAML_EXTERNALGROUPS	externalGroups	<list> `Temporary-staff`	Black list groups, users in these groups are denied access.
CMD_SAML_ATTRIBUTE_ID	id	<string> `sAMAccountName`	Attribute used for id (default: NameID of SAML response).
CMD_SAML_ATTRIBUTE_USERNAME	username	<string> `mailNickname`	Attribute used for username (default: NameID of SAML response).
CMD_SAML_ATTRIBUTE_EMAIL	email	<string> `mail`	Attribute used for email (default: NameID of SAML response if `identifierFormat` is in the default format.)

LDAP

See this guide: Authenticate with LDAP.

Environment Variable	config.json	Example Value	Description
CMD_LDAP_URL	url	<string> `ldap://example.com`	URL of LDAP server.
CMD_LDAP_BINDDN	bindDn	<string> `CN=user1,CN=Users,DC=example,DC=com`	bindDn for LDAP access.
CMD_LDAP_BINDCREDENTIALS	bindCredentials	<string> `M7p@s3wOrd`	bindCredentials for LDAP access.
CMD_LDAP_SEARCHBASE	searchBase	<string> `o=users,dc=example,dc=com`	LDAP directory to begin search from.
CMD_LDAP_SEARCHFILTER	searchFilter	<string> `(uid={{username}})`	LDAP filter to search with.
CMD_LDAP_SEARCHATTRIBUTES	searchAttributes	<list> `displayName, mail`	LDAP attributes to search with (use comma to separate).
CMD_LDAP_USERIDFIELD	useridField	<string> `uidNumber`, `uid`, or `sAMAccountName`	The LDAP field which is used uniquely identify a user on CodiMD.
CMD_LDAP_USERNAMEFIELD	usernameField	<string> `username`	The LDAP field which is used as the username on CodiMD (fallback to userid).
CMD_LDAP_TLS_CA	tlsca	<list> `server-cert.pem, root.pem`	Root CA for LDAP TLS in PEM format (use comma to separate).
CMD_LDAP_PROVIDERNAME	providerName	<string> `My institution`	Optional name to be displayed at login form indicating the LDAP provider.

OAuth - Common OAuth Providers

See this table for common OAuth callback URLs. You can also implement your own OAuth2 provider with these configs.

Google

Environment Variable	config.json	Example Value	Description
CMD_GOOGLE_CLIENTID	clientID	<string> `HWiDIfHvTvKj3_zMwA6aSw`	Google API client id.
CMD_GOOGLE_CLIENTSECRET	clientSecret	<string> `HWiDIfHvTvKj3_zMwA6aSw`	Google API client secret.

GitHub

See this guide.

Environment Variable	config.json	Example Value	Description
CMD_GITHUB_CLIENTID	clientID	<string> `HWiDIfHvTvKj3_zMwA6aSw`	GitHub API client id.
CMD_GITHUB_CLIENTSECRET	clientSecret	<string> `HWiDIfHvTvKj3_zMwA6aSw`	GitHub API client secret.
CMD_GITHUB_ENTERPRISE_URL	enterpriseURL	<string> `http://url-of-github-enterprise`	Url of GitHub Enterprise instance.

GitLab

See this guide.

Environment Variable	config.json	Example Value	Description
CMD_GITLAB_BASEURL	baseURL	<string> `HWiDIfHvTvKj3_zMwA6aSw`	GitLab authentication endpoint. (Default 'GitLab.com')
CMD_GITLAB_CLIENTID	clientID	<string> `HWiDIfHvTvKj3_zMwA6aSw`	GitLab API client id.
CMD_GITLAB_CLIENTSECRET	clientSecret	<string> `HWiDIfHvTvKj3_zMwA6aSw`	GitLab API client secret.
CMD_GITLAB_SCOPE	scope	<string> `read_user`, `api`	GitLab API requested scope. For authentication only, use 'read_user'. If you need gitlab snippet import/export, use 'api'. (Default 'api').
CMD_GITLAB_VERSION	version	<string> `v3`, `v4`	GitLab API version ('v4' for gitlab version > 11, 'v3' otherwise. Default 'v4'),

Mattermost

See this guide.

Environment Variable	config.json	Example Value	Description
CMD_MATTERMOST_BASEURL	baseURL	<string> `example.com`	Mattermost authentication endpoint for versions < 5.0. For version 5.0 and above, see guide.
CMD_MATTERMOST_CLIENTID	clientID	<string> `HWiDIfHvTvKj3_zMwA6aSw`	Mattermost API client id.
CMD_MATTERMOST_CLIENTSECRET	clientSecret	<string> `HWiDIfHvTvKj3_zMwA6aSw`	Mattermost API client secret.

Dropbox

Environment Variable	config.json	Example Value	Description
CMD_DROPBOX_CLIENTID	clientID	<string> `HWiDIfHvTvKj3_zMwA6aSw`	Dropbox API client id.
CMD_DROPBOX_CLIENTSECRET	clientSecret	<string> `HWiDIfHvTvKj3_zMwA6aSw`	Dropbox API client secret.

Facebook

Environment Variable	config.json	Example Value	Description
CMD_FACEBOOK_CLIENTID	clientID	<string> `HWiDIfHvTvKj3_zMwA6aSw`	Facebook API client id.
CMD_FACEBOOK_CLIENTSECRET	clientSecret	<string> `HWiDIfHvTvKj3_zMwA6aSw`	Facebook API client secret.

Twitter

Environment Variable	config.json	Example Value	Description
CMD_TWITTER_CONSUMERKEY	consumeKey	<string> `HWiDIfHvTvKj3_zMwA6aSw`	Twitter API consumer key.
CMD_TWITTER_CONSUMERSECRET	consumerSecret	<string> `HWiDIfHvTvKj3_zMwA6aSw`	Twitter API consumer secret.

OAuth - General OAuth2

Environment Variable	config.json	Example Value	Description
CMD_OAUTH2_BASEURL	baseURL	<string> `https://example.com`
CMD_OAUTH2_USER_PROFILE_URL	userProfileURL	<string> `https://example.com`	Where to get user information after succesful login. The output has to be in JSON format.
CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR	userProfileUsernameAttr	<string> `name`	Username in the JSON returned from the user profile URL.
CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR	userProfileDisplayNameAttr	<string> `display-name`	Display-name in the JSON returned from the user profile URL.
CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR	userProfileEmailAttr	<string> `email`	Email address in the JSON returned from the user profile URL.
CMD_OAUTH2_TOKEN_URL	tokenURL	<string> `https://example.com`	A.K.A. token endpoint from the provider.
CMD_OAUTH2_AUTHORIZATION_URL	authorizationURL	<string> `https://example.com`	Authorization URL of the provider.
CMD_OAUTH2_CLIENT_ID	clientID	<string> `HWiDIfHvTvKj3_zMwA6aSw`	Get this from the provider when registering CodiMD as OAuth2-client.
CMD_OAUTH2_CLIENT_SECRET	clientSecret	<string> `HWiDIfHvTvKj3_zMwA6aSw`	Get this from the provider when registering CodiMD as OAuth2-client.
CMD_OAUTH2_PROVIDERNAME	providerName	<string> `My Company`	Name displayed at login form indicating the OAuth provider.

Development

Environment Variable	config.json	Example Value	Description
DEBUG	debug	`boolean` `true`. `false`	Enable debug mode, show debug level log.
CMD_LOGLEVEL	loglevel	`string` `info`	Change the logging level.
CMD_SOURCE_URL	sourceURL	`string` `https://github.com/<path_to_your_commit>`	CodiMD is licensed under AGPL, if you modified the code, please provide the link to your source code on the entry page with this variable.

Development - Environment Variable Specific Configs

Environment Variable	Example Value	Description
NODE_ENV	`string` `production`, `development`	Set the deployment environment and corresponding settings in `config.json` will apply.
CMD_CONFIG_FILE	`string` `/path/to/config.json`	Change the path to the config file.

SSL

We recommend use nginx or other load balancer for SSL offloading.

Environment Variable	Example Value	Description
CMD_PROTOCOL_USESSL	`boolean` `true`. `false`	Use SSL protocol for resources path (applied only when `domain` is set).

SSL - Config.json Specific Configs

We recommend setting up a reverse proxy with web servers (e.g., Nginx or Apache) in order to use HTTPS. The reasons are:

SSL certificates have to be renewed periodically, we don't want to restart our CodiMD every time.
A SSL certificate is RARELY used only by the CodiMD service, so it doesn't make sense to bundle the certificate within the container.
A dedicated web server is more customizable and has better performance.

The following configs provide basic SSL supports within CodiMD for those who know what they are doing. These configs are only available in the developer-facing config.json file.

config.json	Example Value	Description
useSSL	<boolean> `true`. `false`	Use SSL server (enabling this will also turn on `protocolUseSSL`).
dhParamPath	<string> `./cert/dhparam.pem`	Path to SSL dhparam.
sslKeyPath	<string> `./cert/client.key`	Path to SSL key.
sslCertPath	<string> `./cert/codimd_io.crt`	Path to SSL cert.
sslCAPath	<List> `./cert/COMODORSAAddTrustCA.crt`	A list of path(s) to the chain of SSL CA. The order of the list items has to follow the order of the chain.

Performance

These config values are battle tested and true. If you want to play with them, find them in the config.json file.

config.json	Example Value	Description
staticCacheTime	<integer> `1 * 24 * 60 * 60 * 1000`	static file cache time in milliseconds.
heartbeatInterval	<integer> `5000`	Socket.io heartbeat interval in milliseconds.
heartbeatTimeout	<integer> `10000`	Socket.io heartbeat timeout in milliseconds.
documentMaxLength	<integer> `100000`	Note length maximum in characters.

Resources

These housekeeping configs pertains to the project structure. Find them only in the config.json file.

config.json	Example Value	Description
defaultNotePath	<string> `./public/default.md`	Path to the file that contains content that will be added to all newly created notes.
tmpPath	<string> `./tmp/`	Path to temp directory.
docsPath	<string> `./public/docs`	Path to all pre-loaded documents. Read this guide to customize pre-load notes
viewPath	<string> `./public/views`	Path to pages view templates.
uploadsPath	<string> `./public/uploads`	Path to where user-uploaded images are stored when you set `imageUploadType` to filesystem.

Security

HSTS

Environment Variable	Data Type	Default Value	Example Value	Description
CMD_HSTS_ENABLE	`boolean`	`true`	`true`. `false`	Enable HSTS (only if HTTPS is also enabled).
CMD_HSTS_INCLUDE_SUBDOMAINS	`boolean`	`true`	`true`. `false`	Include subdomains in HSTS.
CMD_HSTS_MAX_AGE	`number`	`31536000`	`31536000`	Max time in seconds to tell clients to keep the HSTS status.
CMD_HSTS_PRELOAD	`boolean`	`true`	`true`. `false`	Allow preloading of the site's HSTS status.

CSP

Environment Variable	Data Type	Default Value	Example Value	Description
CMD_CSP_ENABLE	`boolean`	`true`	`true`. `false`	Enable Content Security Policy.
CMD_CSP_REPORTURI	`string`		`https://<someid>.report-uri.com/r/d/csp/enforce`	Add a URL for CSP reports in case of violations.

tags: `CodiMD` `Docs`

Guest Fernandez2021/12/29 23:23:32

:bulb: **Hint:** You would find most config options duplicated in both the config file and environment variables.

would be nice to also see the default values for everything (Edited)

林博仁 Buo-ren Lin

2024/04/27 20:50:38

The default values are available now?

Syndace

2022/01/31 22:32:26

Default

Don't trust the defaults given here, at least `CMD_ALLOW_ANONYMOUS` seems to default to false in current versions. (Edited)

Guest Marsh2023/02/08 14:42:36

t (Edited)

Himura

2023/05/04 14:11:38

yep, this is outdated https://hackmd.io/@codimd/note-permission#Default-Behavior (Edited)

403 Forbidden - HackMDBuild together with Markdown

HackMD

2023/05/04 14:12:35

Environment Variable

why duplicate? (Edited)

CodiMD Configuration

General

Server Resource URL

Service Listening

Others

Database

Privilege and Privacy

User Privilege

Session

User Features

Configuration for header link style

PlantUML

Image Storage

Imgur

S3

Minio

Azure

Authentication

Email

SAML

LDAP

OAuth - Common OAuth Providers

Google

GitHub

GitLab

Mattermost

Dropbox

Facebook

Twitter

OAuth - General OAuth2

Development

Development - Environment Variable Specific Configs

SSL

SSL - Config.json Specific Configs

Performance

Resources

Security

HSTS

CSP

tags: CodiMD Docs

tags: `CodiMD` `Docs`