diff options
| -rw-r--r-- | README.md | 6 | ||||
| -rw-r--r-- | docs/configuration-config-file.md | 195 | ||||
| -rw-r--r-- | docs/configuration-env-vars.md | 257 | ||||
| -rw-r--r-- | docs/configuration.md | 266 | ||||
| -rw-r--r-- | docs/setup/manual-setup.md | 13 |
5 files changed, 274 insertions, 463 deletions
@@ -50,10 +50,8 @@ similar project. ## Configuration -Theres two main ways to configure your CodiMD instance: -[Config file](docs/configuration-config-file.md) or -[environment variables](docs/configuration-env-vars.md). You can choose what -works best for you. +Theres two main ways to [configure](docs/configuration.md) your CodiMD instance: +config file or environment variables. You can choose what works best for you. CodiMD can integrate with diff --git a/docs/configuration-config-file.md b/docs/configuration-config-file.md deleted file mode 100644 index 5134af7f..00000000 --- a/docs/configuration-config-file.md +++ /dev/null @@ -1,195 +0,0 @@ -Configuration Using Config file -=== - -You can choose to configure CodiMD with either a config file or with -[environment variables](configuration-env-vars.md). The config file is processed -in [`lib/config/index.js`](../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`](../lib/config/default.js), -in case you wonder if you even need to override it. - -Environment variables take precedence over configurations from the config files. -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. - - -## Node.JS - -| variables | example values | description | -| --------- | ------ | ----------- | -| `debug` | `true` or `false` | set debug mode, show more logs | - - -## CodiMD basics - -| variables | example values | description | -| --------- | ------ | ----------- | -| `allowPDFExport` | `true` | Whether or not PDF export is offered. | -| `db` | `{ "dialect": "sqlite", "storage": "./db.codimd.sqlite" }` | set the db configs, [see more here](http://sequelize.readthedocs.org/en/latest/api/sequelize/) | -| `dbURL` | `mysql://localhost:3306/database` | Set the db in URL style. If set, then the relevant `db` config entries will be overridden. | -| `forbiddenNoteIDs` | `['robots.txt']` | disallow creation of notes, even if `allowFreeUrl` is `true` | -| `loglevel` | `info` | Defines what kind of logs are provided to stdout. Available options: `debug`, `verbose`, `info`, `warn`, `error` | -| `imageUploadType` | `imgur`, `s3`, `minio`, `azure`, `lutim` or `filesystem`(default) | Where to upload images. For S3, see our Image Upload Guides for [S3](guides/s3-image-upload.md) or [MinIO](guides/minio-image-upload.md)| -| `sourceURL` | `https://github.com/codimd/server/tree/<current commit>` | Provides the link to the source code of CodiMD on the entry page (Please, make sure you change this when you run a modified version) | -| `staticCacheTime` | `1 * 24 * 60 * 60 * 1000` | static file cache time | -| `tooBusyLag` | `70` | CPU time for one event loop tick until node throttles connections. (milliseconds) | -| `heartbeatInterval` | `5000` | socket.io heartbeat interval | -| `heartbeatTimeout` | `10000` | socket.io heartbeat timeout | -| `documentMaxLength` | `100000` | note max length | - - -## CodiMD paths stuff - -these are rarely used for various reasons. - -| variables | example values | description | -| --------- | ------ | ----------- | -| `defaultNotePath` | `./public/default.md` | default note file path<sup>1</sup>, empty notes will be created with this template. | -| `dhParamPath` | `./cert/dhparam.pem` | SSL dhparam path<sup>1</sup> (only need when you set `useSSL`) | -| `sslCAPath` | `['./cert/COMODORSAAddTrustCA.crt']` | SSL ca chain<sup>1</sup> (only need when you set `useSSL`) | -| `sslCertPath` | `./cert/codimd_io.crt` | SSL cert path<sup>1</sup> (only need when you set `useSSL`) | -| `sslKeyPath` | `./cert/client.key` | SSL key path<sup>1</sup> (only need when you set `useSSL`) | -| `tmpPath` | `./tmp/` | temp directory path<sup>1</sup> | -| `docsPath` | `./public/docs` | docs directory path<sup>1</sup> | -| `viewPath` | `./public/views` | template directory path<sup>1</sup> | -| `uploadsPath` | `./public/uploads` | uploads directory<sup>1</sup> - needs to be persistent when you use imageUploadType `filesystem` | - - -## CodiMD Location - -| variables | example values | description | -| --------- | ------ | ----------- | -| `domain` | `localhost` | domain name | -| `urlPath` | `codimd` | sub URL path, like `www.example.com/<urlpath>` | -| `host` | `localhost` | interface/ip to listen on | -| `port` | `80` | port to listen on | -| `path` | `/var/run/codimd.sock` | path to UNIX domain socket to listen on (if specified, `host` and `port` are ignored) | -| `protocolUseSSL` | `true` or `false` | set to use SSL protocol for resources path (only applied when domain is set) | -| `useSSL` | `true` or `false` | set to use SSL server (if `true`, will auto turn on `protocolUseSSL`) | -| `urlAddPort` | `true` or `false` | set to add port on callback URL (ports `80` or `443` won't be applied) (only applied when domain is set) | -| `allowOrigin` | `['localhost']` | domain name whitelist | - - -## CSP and HSTS - -| variables | example values | description | -| --------- | ------ | ----------- | -| `hsts` | `{"enable": true, "maxAgeSeconds": 31536000, "includeSubdomains": true, "preload": true}` | [HSTS](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) options to use with HTTPS (default is the example value, max age is a year) | -| `csp` | `{"enable": true, "directives": {"scriptSrc": "trustworthy-scripts.example.com"}, "upgradeInsecureRequests": "auto", "addDefaults": true}` | Configures [Content Security Policy](https://helmetjs.github.io/docs/csp/). Directives are passed to Helmet - see [their documentation](https://helmetjs.github.io/docs/csp/) for more information on the format. Some defaults are added to the configured values so that the application doesn't break. To disable this behaviour, set `addDefaults` to `false`. Further, if `usecdn` is on, some CDN locations are allowed too. By default (`auto`), insecure (HTTP) requests are upgraded to HTTPS via CSP if `useSSL` is on. To change this behaviour, set `upgradeInsecureRequests` to either `true` or `false`. | - -## Privacy and External Requests - -| variables | example values | description | -| --------- | ------ | ----------- | -| `allowGravatar` | `true` or `false` | set to `false` to disable [Libravatar](https://www.libravatar.org/) as profile picture source on your instance. Libravatar is a federated open-source alternative to Gravatar. | -| `useCDN` | `true` or `false` | set to use CDN resources or not (default is `false`) | - -## Users and Privileges - -| variables | example values | description | -| --------- | ------ | ----------- | -| `allowAnonymous` | `true` or `false` | Set to allow anonymous usage (default is `true`). | -| `allowAnonymousEdits` | `true` or `false` | If `allowAnonymous` is `true`: allow users to select `freely` permission, allowing guests to edit existing notes (default is `false`). | -| `allowFreeURL` | `true` or `false` | Set to allow new note creation by accessing a nonexistent note URL. This is the behavior familiar from [Etherpad](https://github.com/ether/etherpad-lite). | -| `defaultPermission` | `freely`, `editable`, `limited`, `locked`, `protected` or `private` | Set notes default permission (only applied on signed-in users). | -| `sessionName` | `connect.sid` | Cookie session name. | -| `sessionLife` | `14 * 24 * 60 * 60 * 1000` (14 days) | Cookie session life time in milliseconds. | -| `sessionSecret` | `secret` | Cookie session secret. If none is set, one will randomly generated on each startup, meaning all your users will be logged out. | - - -## Login methods - -### Email (local account) - -| variables | example values | description | -| --------- | ------ | ----------- | -| `email` | `true` or `false` | Set to allow email sign-in. The default is `true`. | -| `allowEmailRegister` | `true` or `false` | 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` is `false`. The default for `allowEmailRegister` is `true`. | - -### Dropbox Login - -| variables | example values | description | -| --------- | ------ | ----------- | -| `dropbox` | `{clientID: ..., clientSecret: ...}` | An object containing the client ID and the client secret obtained by the [Dropbox developer tools](https://www.dropbox.com/developers/apps) | - -### Facebook Login - -| variables | example values | description | -| --------- | ------ | ----------- | -| `facebook` | `{clientID: ..., clientSecret: ...}` | An object containing the client ID and the client secret obtained by the [Facebook app console](https://developers.facebook.com/apps) | - -### GitHub Login - -| variables | example values | description | -| --------- | ------ | ----------- | -| `github` | `{clientID: ..., clientSecret: ...}` | An object containing the client ID and the client secret obtained by the GitHub developer page. For more details have a look at the [GitHub auth guide](guides/auth/github.md). | - -### GitLab Login - -| variables | example values | description | -| --------- | ------ | ----------- | -| `gitlab` | `{baseURL: ..., scope: ..., version: ..., clientID: ..., clientSecret: ...}` | An object containing your GitLab application data. Refer to the [GitLab guide](guides/auth/gitlab-self-hosted.md) for more details! | - -### Google Login - -| variables | example values | description | -| --------- | ------ | ----------- | -| `google` | `{clientID: ..., clientSecret: ..., hostedDomain: ...}` | An object containing the client ID and the client secret obtained by the [Google API console](https://console.cloud.google.com/apis) | - -### LDAP Login - -| variables | example values | description | -| --------- | ------ | ----------- | -| `ldap` | `{providerName: ..., url: ..., bindDn: ..., bindCredentials: ..., searchBase: ..., searchFilter: ..., searchAttributes: ..., usernameField: ..., useridField: ..., tlsca: ...}` | An object detailing the LDAP connection. Refer to the [LDAP-AD guide](guides/auth/ldap-AD.md) for more details! | - -### Mattermost Login - -| variables | example values | description | -| --------- | ------ | ----------- | -| `mattermost` | `{baseURL: ..., clientID: ..., clientSecret: ...}` | An object containing the base URL of your Mattermost application data. Refer to the [Mattermost guide](guides/auth/mattermost-self-hosted.md) for more details! | - -### OAuth2 Login - -| variables | example values | description | -| --------- | ------ | ----------- | -| `oauth2` | `{baseURL: ..., userProfileURL: ..., userProfileUsernameAttr: ..., userProfileDisplayNameAttr: ..., userProfileEmailAttr: ..., tokenURL: ..., authorizationURL: ..., clientID: ..., clientSecret: ...}` | An object detailing your OAuth2 provider. Refer to the [Mattermost](guides/auth/mattermost-self-hosted.md) or [Nextcloud](guides/auth/nextcloud.md) examples for more details!| - -### SAML Login - -| variables | example values | description | -| --------- | ------ | ----------- | -| `saml` | `{idpSsoUrl: ..., idpCert: ..., issuer: ..., identifierFormat: ..., disableRequestedAuthnContext: ..., groupAttribute: ..., externalGroups: [], requiredGroups: [], attribute: {id: ..., username: ..., email: ...}}` | An object detailing your SAML provider. Refer to the [OneLogin](guides/auth/saml-onelogin.md) and [SAML](guides/auth/saml.md) guides for more details! | - -### Twitter Login - -| variables | example values | description | -| --------- | ------ | ----------- | -| `twitter` | `{consumerKey: ..., consumerSecret: ...}` | An object containing the consumer key and secret obtained by the [Twitter developer tools](https://developer.twitter.com/apps). For more details have a look at the [Twitter auth guide](guides/auth/twitter.md) | - -## Upload Storage - -Most of these have never been documented for the config.json, feel free to expand these - - -### Amazon S3 - -| variables | example values | description | -| --------- | ------ | ----------- | -| `s3` | `{ "accessKeyId": "YOUR_S3_ACCESS_KEY_ID", "secretAccessKey": "YOUR_S3_ACCESS_KEY", "region": "YOUR_S3_REGION" }` | When `imageuploadtype` be set to `s3`, you would also need to setup this key, check our [S3 Image Upload Guide](guides/s3-image-upload.md) | -| `s3bucket` | `YOUR_S3_BUCKET_NAME` | bucket name when `imageUploadType` is set to `s3` or `minio` | - -### Azure Blob Storage -### Imgur -### MinIO - -| variables | example values | description | -| --------- | ------ | ----------- | -| `minio` | `{ "accessKey": "YOUR_MINIO_ACCESS_KEY", "secretKey": "YOUR_MINIO_SECRET_KEY", "endpoint": "YOUR_MINIO_HOST", port: 9000, secure: true }` | When `imageUploadType` is set to `minio`, you need to set this key. Also check out our [Minio Image Upload Guide](guides/minio-image-upload.md) | - -### Lutim - -| variables | example values | description | -| --------- | ------ | ----------- | -|`lutim`| `{"url": "YOUR_LUTIM_URL"}`| When `imageUploadType` is set to `lutim`, you can setup the lutim url| - -<sup>1</sup>: relative paths are based on CodiMD's base directory diff --git a/docs/configuration-env-vars.md b/docs/configuration-env-vars.md deleted file mode 100644 index d203c80b..00000000 --- a/docs/configuration-env-vars.md +++ /dev/null @@ -1,257 +0,0 @@ -Configuration Using Environment variables -=== - -You can choose to configure CodiMD with either a -[config file](configuration-config-file.md) or with environment variables. -Environment variables are processed in -[`lib/config/environment.js`](../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`](../lib/config/default.js), -in case you wonder if you even need to override it. - -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. - - -## Node.JS - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `NODE_ENV` | `production` or `development` | set current environment (will apply corresponding settings in the `config.json`) | -| `DEBUG` | `true` or `false` | set debug mode; show more logs | - - -## CodiMD basics - -defaultNotePath can't be set from env-vars - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_ALLOW_PDF_EXPORT` | `true` or `false` | Enable or disable PDF exports | -| `CMD_CONFIG_FILE` | `/path/to/config.json` | optional override for the path to CodiMD's config file | -| `CMD_DB_URL` | `mysql://localhost:3306/database` | Set the db in URL style. If set, then the relevant `db` config entries will be overridden. | -| `CMD_LOGLEVEL` | `info`, `debug` ... | Defines what kind of logs are provided to stdout. | -| `CMD_FORBIDDEN_NOTE_IDS` | `'robots.txt'` | disallow creation of notes, even if `CMD_ALLOW_FREEURL` is `true` | -| `CMD_IMAGE_UPLOAD_TYPE` | `imgur`, `s3`, `minio`, `lutim` or `filesystem` | Where to upload images. For S3, see our Image Upload Guides for [S3](guides/s3-image-upload.md) or [Minio](guides/minio-image-upload.md), also there's a whole section on their respective env vars below. | -| `CMD_SOURCE_URL` | `https://github.com/codimd/server/tree/<current commit>` | Provides the link to the source code of CodiMD on the entry page (Please, make sure you change this when you run a modified version) | -| `CMD_TOOBUSY_LAG` | `70` | CPU time for one event loop tick until node throttles connections. (milliseconds) | - - -## CodiMD Location - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_DOMAIN` | `codimd.org` | domain name | -| `CMD_URL_PATH` | `codimd` | If CodiMD is run from a subdirectory like `www.example.com/<urlpath>` | -| `CMD_HOST` | `localhost` | interface/ip to listen on | -| `CMD_PORT` | `80` | port to listen on | -| `CMD_PATH` | `/var/run/codimd.sock` | path to UNIX domain socket to listen on (if specified, `CMD_HOST` and `CMD_PORT` are ignored) | -| `CMD_PROTOCOL_USESSL` | `true` or `false` | set to use SSL protocol for resources path (only applied when domain is set) | -| `CMD_URL_ADDPORT` | `true` or `false` | set to add port on callback URL (ports `80` or `443` won't be applied) (only applied when domain is set) | -| `CMD_ALLOW_ORIGIN` | `localhost, codimd.org` | domain name whitelist (use comma to separate) | - - -## CSP and HSTS - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_CSP_ENABLE` | `true` | whether to enable Content Security Policy (directives cannot be configured with environment variables) | -| `CMD_CSP_REPORTURI` | `https://<someid>.report-uri.com/r/d/csp/enforce` | Allows to add a URL for CSP reports in case of violations | -| `CMD_HSTS_ENABLE` | ` true` | set to enable [HSTS](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) if HTTPS is also enabled (default is ` true`) | -| `CMD_HSTS_INCLUDE_SUBDOMAINS` | `true` | set to include subdomains in HSTS (default is `true`) | -| `CMD_HSTS_MAX_AGE` | `31536000` | max duration in seconds to tell clients to keep HSTS status (default is a year) | -| `CMD_HSTS_PRELOAD` | `true` | whether to allow preloading of the site's HSTS status (e.g. into browsers) | - - -## Privacy and External Requests - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_ALLOW_GRAVATAR` | `true` or `false` | set to `false` to disable [Libravatar](https://www.libravatar.org/) as profile picture source on your instance. Libravatar is a federated open-source alternative to Gravatar. | -| `CMD_USECDN` | `true` or `false` | set to use CDN resources or not| - - -## Users and Privileges - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_ALLOW_ANONYMOUS` | `true` or `false` | Set to allow anonymous usage (default is `true`). | -| `CMD_ALLOW_ANONYMOUS_EDITS` | `true` or `false` | If `allowAnonymous` is `false`: allow users to select `freely` permission, allowing guests to edit existing notes (default is `true`). | -| `CMD_ALLOW_FREEURL` | `true` or `false` | Set to allow new note creation by accessing a nonexistent note URL. This is the behavior familiar from [Etherpad](https://github.com/ether/etherpad-lite). | -| `CMD_DEFAULT_PERMISSION` | `freely`, `editable`, `limited`, `locked`, `protected` or `private` | Set notes default permission (only applied on signed-in users). | -| `CMD_SESSION_LIFE` | `1209600000` (14 days) | Cookie session life time in milliseconds. | -| `CMD_SESSION_SECRET` | no example | 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. | - - -## Login methods - -### Email (local account) - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_EMAIL` | `true` or `false` | Set to allow email sign-in. The default is `true`. | -| `CMD_ALLOW_EMAIL_REGISTER` | `true` or `false` | 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 `CMD_EMAIL` is `false`. The default for `CMD_ALLOW_EMAIL_REGISTER` is `true`. | - - -### Dropbox Login - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_DROPBOX_CLIENTID` | no example | Dropbox API client id | -| `CMD_DROPBOX_CLIENTSECRET` | no example | Dropbox API client secret | - - -### Facebook Login - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_FACEBOOK_CLIENTID` | no example | Facebook API client id | -| `CMD_FACEBOOK_CLIENTSECRET` | no example | Facebook API client secret | - - -### GitHub Login - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_GITHUB_CLIENTID` | no example | GitHub API client id | -| `CMD_GITHUB_CLIENTSECRET` | no example | GitHub API client secret | - - -### GitLab Login - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_GITLAB_SCOPE` | `read_user` or `api` | GitLab API requested scope (default is `api`) (GitLab snippet import/export need `api` scope) | -| `CMD_GITLAB_BASEURL` | no example | GitLab authentication endpoint, set to use other endpoint than GitLab.com (optional) | -| `CMD_GITLAB_CLIENTID` | no example | GitLab API client id | -| `CMD_GITLAB_CLIENTSECRET` | no example | GitLab API client secret | -| `CMD_GITLAB_VERSION` | no example | GitLab API version (v3 or v4) | - - -### Google Login - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_GOOGLE_CLIENTID` | no example | Google API client id | -| `CMD_GOOGLE_CLIENTSECRET` | no example | Google API client secret | -| `CMD_GOOGLE_HOSTEDDOMAIN` | `example.com` | Provided only if the user belongs to a hosted domain. default is `undefined` | - - -### LDAP Login - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_LDAP_URL` | `ldap://example.com` | URL of LDAP server | -| `CMD_LDAP_BINDDN` | no example | bindDn for LDAP access | -| `CMD_LDAP_BINDCREDENTIALS` | no example | bindCredentials for LDAP access | -| `CMD_LDAP_SEARCHBASE` | `o=users,dc=example,dc=com` | LDAP directory to begin search from | -| `CMD_LDAP_SEARCHFILTER` | `(uid={{username}})` | LDAP filter to search with | -| `CMD_LDAP_SEARCHATTRIBUTES` | `displayName, mail` | LDAP attributes to search with (use comma to separate) | -| `CMD_LDAP_USERIDFIELD` | `uidNumber` or `uid` or `sAMAccountName` | The LDAP field which is used uniquely identify a user on CodiMD | -| `CMD_LDAP_USERNAMEFIELD` | Fallback to userid | The LDAP field which is used as the username on CodiMD | -| `CMD_LDAP_TLS_CA` | `server-cert.pem, root.pem` | Root CA for LDAP TLS in PEM format (use comma to separate) | -| `CMD_LDAP_PROVIDERNAME` | `My institution` | Optional name to be displayed at login form indicating the LDAP provider | - - -### Mattermost Login - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_MATTERMOST_BASEURL` | no example | Mattermost authentication endpoint for versions below 5.0. For Mattermost version 5.0 and above, see [guide](guides/auth/mattermost-self-hosted.md). | -| `CMD_MATTERMOST_CLIENTID` | no example | Mattermost API client id | -| `CMD_MATTERMOST_CLIENTSECRET` | no example | Mattermost API client secret | - - -### OAuth2 Login - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_OAUTH2_USER_PROFILE_URL` | `https://example.com` | Where to retrieve information about a user after successful login. Needs to output JSON. (no default value) Refer to the [Mattermost](guides/auth/mattermost-self-hosted.md) or [Nextcloud](guides/auth/nextcloud.md) examples for more details on all of the `CMD_OAUTH2...` options. | -| `CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR` | `name` | where to find the username in the JSON from the user profile URL. (no default value)| -| `CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR` | `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` | `email` | where to find the email address in the JSON from the user profile URL. (no default value) | -| `CMD_OAUTH2_TOKEN_URL` | `https://example.com` | sometimes called token endpoint, please refer to the documentation of your OAuth2 provider (no default value) | -| `CMD_OAUTH2_AUTHORIZATION_URL` | `https://example.com` | authorization URL of your provider, please refer to the documentation of your OAuth2 provider (no default value) | -| `CMD_OAUTH2_CLIENT_ID` | `afae02fckafd...` | you will get this from your OAuth2 provider when you register CodiMD as OAuth2-client, (no default value) | -| `CMD_OAUTH2_CLIENT_SECRET` | `afae02fckafd...` | you will get this from your OAuth2 provider when you register CodiMD as OAuth2-client, (no default value) | -| `CMD_OAUTH2_PROVIDERNAME` | `My institution` | Optional name to be displayed at login form indicating the oAuth2 provider | - - -### SAML Login - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_SAML_IDPSSOURL` | `https://idp.example.com/sso` | authentication endpoint of IdP. for details, see [guide](guides/auth/saml-onelogin.md). | -| `CMD_SAML_IDPCERT` | `/path/to/cert.pem` | certificate file path of IdP in PEM format | -| `CMD_SAML_ISSUER` | no example | Issuer to supply to identity provider (optional, default: `serverURL` config)" | -| `CMD_SAML_DISABLEREQUESTEDAUTHNCONTEXT` | `true` or `false` | true to allow any authentication method, false restricts to password authentication (PasswordProtectedTransport) method (default: false) | -| `CMD_SAML_IDENTIFIERFORMAT` | no example | name identifier format (optional, default: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`) | -| `CMD_SAML_GROUPATTRIBUTE` | `memberOf` | attribute name for group list (optional) | -| `CMD_SAML_REQUIREDGROUPS` | `codimd-users` | group names that allowed (use vertical bar to separate) (optional) | -| `CMD_SAML_EXTERNALGROUPS` | `Temporary-staff` | group names that not allowed (use vertical bar to separate) (optional) | -| `CMD_SAML_ATTRIBUTE_ID` | `sAMAccountName` | attribute map for `id` (optional, default: NameID of SAML response) | -| `CMD_SAML_ATTRIBUTE_USERNAME` | `mailNickname` | attribute map for `username` (optional, default: NameID of SAML response) | -| `CMD_SAML_ATTRIBUTE_EMAIL` | `mail` | attribute map for `email` (optional, default: NameID of SAML response if `CMD_SAML_IDENTIFIERFORMAT` is default) | - - -### Twitter Login - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_TWITTER_CONSUMERKEY` | no example | Twitter API consumer key | -| `CMD_TWITTER_CONSUMERSECRET` | no example | Twitter API consumer secret | - - -## Upload Storage - -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. - - -### Amazon S3 - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_S3_ACCESS_KEY_ID` | no example | AWS access key id | -| `CMD_S3_SECRET_ACCESS_KEY` | no example | AWS secret key | -| `CMD_S3_REGION` | `ap-northeast-1` | AWS S3 region | -| `CMD_S3_BUCKET` | no example | AWS S3 bucket name | - - -### Azure Blob Storage - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_AZURE_CONNECTION_STRING` | no example | Azure Blob Storage connection string | -| `CMD_AZURE_CONTAINER` | no example | Azure Blob Storage container name (automatically created if non existent) | - - -### imgur - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_IMGUR_CLIENTID` | no example | Imgur API client id | - - -### Minio - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_MINIO_ACCESS_KEY` | no example | Minio access key | -| `CMD_MINIO_SECRET_KEY` | no example | Minio secret key | -| `CMD_MINIO_ENDPOINT` | `minio.example.org` | Address of your Minio endpoint/instance | -| `CMD_MINIO_PORT` | `9000` | Port that is used for your Minio instance | -| `CMD_MINIO_SECURE` | `true` | If set to `true` HTTPS is used for Minio | - - -### Lutim - -| variable | example value | description | -| -------- | ------------- | ----------- | -| `CMD_LUTIM_URL` | `https://framapic.org/` | When `CMD_IMAGE_UPLOAD_TYPE` is set to `lutim`, you can setup the lutim url | - -**Note:** *Due to the rename process we renamed all `HMD_`-prefix variables to be `CMD_`-prefixed. The old ones continue to work.* - -**Note:** *relative paths are based on CodiMD's base directory* diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 00000000..20f853de --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,266 @@ +# Configuration + +You can choose to configure CodiMD 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`](../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`](../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`](../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`](../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.* + +## Node.JS + +| config file | environment | example value | description | +| ----------- | ----------- | ----------------------------- | -------------------------------------------------------------------------------- | +| | `NODE_ENV` | `production` or `development` | set current environment (will apply corresponding settings in the `config.json`) | +| `debug` | `DEBUG` | `true` or `false` | set debug mode, show more logs | + +## CodiMD basics + +| config file | environment | example value | description | +| ------------------- | ------------------------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `allowPDFExport` | `CMD_ALLOW_PDF_EXPORT` | `true` or `false` | Enable or disable PDF exports | +| | `CMD_CONFIG_FILE` | `/path/to/config.json` | optional override for the path to CodiMD's config file | +| `db` | | `{ "dialect": "sqlite", "storage": "./db.codimd.sqlite" }` | set the db configs, [see more here](http://sequelize.readthedocs.org/en/latest/api/sequelize/) | +| `dbURL` | `CMD_DB_URL` | `mysql://localhost:3306/database` | Set the db in URL style. If set, then the relevant `db` config entries will be overridden. | +| `loglevel` | `CMD_LOGLEVEL` | `info`, `debug` ... | Defines what kind of logs are provided to stdout. Available options: `debug`, `verbose`, `info`, `warn`, `error` | +| `forbiddenNoteIDs` | `CMD_FORBIDDEN_NOTE_IDS` | `['robots.txt']` or `'robots.txt'` | disallow creation of notes, even if `allowFreeUrl` or `CMD_ALLOW_FREEURL` is `true` | +| `imageUploadType` | `CMD_IMAGE_UPLOAD_TYPE` | `imgur`, `s3`, `minio`, `azure`, `lutim` or `filesystem` (default) | Where to upload images. For S3, see our Image Upload Guides for [S3](guides/s3-image-upload.md) or [Minio](guides/minio-image-upload.md), also there's a whole section on their respective env vars below. | +| `sourceURL` | `CMD_SOURCE_URL` | `https://github.com/codimd/server/tree/<current commit>` | Provides the link to the source code of CodiMD on the entry page (Please, make sure you change this when you run a modified version) | +| `tooBusyLag` | `CMD_TOOBUSY_LAG` | `70` | CPU time for one event loop tick until node throttles connections. (milliseconds) | +| `staticCacheTime` | | `1 * 24 * 60 * 60 * 1000` | static file cache time | +| `heartbeatInterval` | | `5000` | socket.io heartbeat interval | +| `heartbeatTimeout` | | `10000` | socket.io heartbeat timeout | +| `documentMaxLength` | | `100000` | note max length | + +## CodiMD paths stuff + +these are rarely used for various reasons. + +| config file | environment | example values | description | +| ----------------- | ----------- | ------------------------------------ | ------------------------------------------------------------------------------------------------ | +| `defaultNotePath` | | `./public/default.md` | default note file path<sup>1</sup>, empty notes will be created with this template. | +| `dhParamPath` | | `./cert/dhparam.pem` | SSL dhparam path<sup>1</sup> (only need when you set `useSSL`) | +| `sslCAPath` | | `['./cert/COMODORSAAddTrustCA.crt']` | SSL ca chain<sup>1</sup> (only need when you set `useSSL`) | +| `sslCertPath` | | `./cert/codimd_io.crt` | SSL cert path<sup>1</sup> (only need when you set `useSSL`) | +| `sslKeyPath` | | `./cert/client.key` | SSL key path<sup>1</sup> (only need when you set `useSSL`) | +| `tmpPath` | | `./tmp/` | temp directory path<sup>1</sup> | +| `docsPath` | | `./public/docs` | docs directory path<sup>1</sup> | +| `viewPath` | | `./public/views` | template directory path<sup>1</sup> | +| `uploadsPath` | | `./public/uploads` | uploads directory<sup>1</sup> - needs to be persistent when you use imageUploadType `filesystem` | + +**Note:** *relative paths are based on CodiMD's base directory* + +## CodiMD Location + +| config file | environment | example value | description | +| ---------------- | --------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| `domain` | `CMD_DOMAIN` | `localhost`, `codimd.org` | domain name | +| `urlPath` | `CMD_URL_PATH` | `codimd` | If CodiMD is run from a subdirectory like `www.example.com/<urlpath>` | +| `host` | `CMD_HOST` | `localhost` | interface/ip to listen on | +| `port` | `CMD_PORT` | `80` | port to listen on | +| `path` | `CMD_PATH` | `/var/run/codimd.sock` | path to UNIX domain socket to listen on (if specified, `host` or `CMD_HOST` and `port` or `CMD_PORT` are ignored) | +| `protocolUseSSL` | `CMD_PROTOCOL_USESSL` | `true` or `false` | set to use SSL protocol for resources path (only applied when domain is set) | +| `useSSL` | | `true` or `false` | set to use SSL server (if `true`, will auto turn on `protocolUseSSL`) | +| `urlAddPort` | `CMD_URL_ADDPORT` | `true` or `false` | set to add port on callback URL (ports `80` or `443` won't be applied) (only applied when domain is set) | +| `allowOrigin` | `CMD_ALLOW_ORIGIN` | `['localhost']`, `['codimd.org']`, `localhost, codimd.org` | domain name whitelist (use comma to separate) | + +## CSP and HSTS + +| config file | environment | example value | description | +| ----------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `hsts` | | `{"enable": true, "maxAgeSeconds": 31536000, "includeSubdomains": true, "preload": true}` | [HSTS](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) options to use with HTTPS (default is the example value, max age is a year) | +| | `CMD_HSTS_ENABLE` | ` true` | set to enable [HSTS](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) if HTTPS is also enabled (default is ` true`) | +| | `CMD_HSTS_INCLUDE_SUBDOMAINS` | `true` | set to include subdomains in HSTS (default is `true`) | | +| | `CMD_HSTS_MAX_AGE` | `31536000` | max duration in seconds to tell clients to keep HSTS status (default is a year) | | +| | `CMD_HSTS_PRELOAD` | `true` | whether to allow preloading of the site's HSTS status (e.g. into browsers) | | +| `csp` | | `{"enable": true, "directives": {"scriptSrc": "trustworthy-scripts.example.com"}, "upgradeInsecureRequests": "auto", "addDefaults": true}` | Configures [Content Security Policy](https://helmetjs.github.io/docs/csp/). Directives are passed to Helmet - see [their documentation](https://helmetjs.github.io/docs/csp/) for more information on the format. Some defaults are added to the configured values so that the application doesn't break. To disable this behaviour, set `addDefaults` to `false`. Further, if `usecdn` is on, some CDN locations are allowed too. By default (`auto`), insecure (HTTP) requests are upgraded to HTTPS via CSP if `useSSL` is on. To change this behaviour, set `upgradeInsecureRequests` to either `true` or `false`. | +| | `CMD_CSP_ENABLE` | `true` | whether to enable Content Security Policy (directives cannot be configured with environment variables) | +| | `CMD_CSP_REPORTURI` | `https://<someid>.report-uri.com/r/d/csp/enforce` | Allows to add a URL for CSP reports in case of violations | | + +## Privacy and External Requests + +| config file | environment | example value | description | +| --------------- | -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `allowGravatar` | `CMD_ALLOW_GRAVATAR` | `true` or `false` | set to `false` to disable [Libravatar](https://www.libravatar.org/) as profile picture source on your instance. Libravatar is a federated open-source alternative to Gravatar. | +| `useCDN` | `CMD_USECDN` | `true` or `false` | set to use CDN resources or not (default is `false`) | + +## Users and Privileges + +| config file | environment | example value | description | +| --------------------- | --------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `allowAnonymous` | `CMD_ALLOW_ANONYMOUS` | `true` or `false` | Set to allow anonymous usage (default is `true`). | +| `allowAnonymousEdits` | `CMD_ALLOW_ANONYMOUS_EDITS` | `true` or `false` | If `allowAnonymous` is `false`: allow users to select `freely` permission, allowing guests to edit existing notes (default is `false`). | +| `allowFreeURL` | `CMD_ALLOW_FREEURL` | `true` or `false` | Set to allow new note creation by accessing a nonexistent note URL. This is the behavior familiar from [Etherpad](https://github.com/ether/etherpad-lite). | +| `defaultPermission` | `CMD_DEFAULT_PERMISSION` | `freely`, `editable`, `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. | + +## Login methods + +### Email (local account) + +| config file | environment | example value | description | +| -------------------- | -------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `email` | `CMD_EMAIL` | `true` or `false` | Set to allow email sign-in. The default is `true`. | +| `allowEmailRegister` | `CMD_ALLOW_EMAIL_REGISTER` | `true` or `false` | 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`. | + +### Dropbox Login + +| config file | environment | example value | description | +| ----------- | -------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `dropbox` | | `{clientID: ..., clientSecret: ...}` | An object containing the client ID and the client secret obtained by the [Dropbox developer tools](https://www.dropbox.com/developers/apps) | +| | `CMD_DROPBOX_CLIENTID` | no example | Dropbox API client id | +| | `CMD_DROPBOX_CLIENTSECRET` | no example | Dropbox API client secret | + +### Facebook Login + +| config file | environment | example value | description | +| ----------- | --------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | +| `facebook` | | `{clientID: ..., clientSecret: ...}` | An object containing the client ID and the client secret obtained by the [Facebook app console](https://developers.facebook.com/apps) | +| | `CMD_FACEBOOK_CLIENTID` | no example | Facebook API client id | +| | `CMD_FACEBOOK_CLIENTSECRET` | no example | Facebook API client secret | + +### GitHub Login + +| config file | environment | example value | description | +| ----------- | ------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `github` | | `{clientID: ..., clientSecret: ...}` | An object containing the client ID and the client secret obtained by the GitHub developer page. For more details have a look at the [GitHub auth guide](guides/auth/github.md). | +| | `CMD_GITHUB_CLIENTID` | no example | GitHub API client id | +| | `CMD_GITHUB_CLIENTSECRET` | no example | GitHub API client secret | + +### GitLab Login + +| config file | environment | example value | description | +| ----------- | ------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `gitlab` | | `{baseURL: ..., scope: ..., version: ..., clientID: ..., clientSecret: ...}` | An object containing your GitLab application data. Refer to the [GitLab guide](guides/auth/gitlab-self-hosted.md) for more details! | +| | `CMD_GITLAB_SCOPE` | `read_user` or `api` | GitLab API requested scope (default is `api`) (GitLab snippet import/export need `api` scope) | +| | `CMD_GITLAB_BASEURL` | no example | GitLab authentication endpoint, set to use other endpoint than GitLab.com (optional) | +| | `CMD_GITLAB_CLIENTID` | no example | GitLab API client id | +| | `CMD_GITLAB_CLIENTSECRET` | no example | GitLab API client secret | +| | `CMD_GITLAB_VERSION` | no example | GitLab API version (v3 or v4) | + +### Google Login + +| config file | environment | example value | description | +| ----------- | ------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `google` | | `{clientID: ..., clientSecret: ..., hostedDomain: ...}` | An object containing the client ID and the client secret obtained by the [Google API console](https://console.cloud.google.com/apis) | +| | `CMD_GOOGLE_CLIENTID` | no example | Google API client id | +| | `CMD_GOOGLE_CLIENTSECRET` | no example | Google API client secret | +| | `CMD_GOOGLE_HOSTEDDOMAIN` | `example.com` | Provided only if the user belongs to a hosted domain. default is `undefined` | + +### LDAP Login + +| config file | environment | example value | description | +| ----------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| `ldap` | | `{providerName: ..., url: ..., bindDn: ..., bindCredentials: ..., searchBase: ..., searchFilter: ..., searchAttributes: ..., usernameField: ..., useridField: ..., tlsca: ...}` | An object detailing the LDAP connection. Refer to the [LDAP-AD guide](guides/auth/ldap-AD.md) for more details! | +| | `CMD_LDAP_URL` | `ldap://example.com` | URL of LDAP server | +| | `CMD_LDAP_BINDDN` | no example | bindDn for LDAP access | +| | `CMD_LDAP_BINDCREDENTIALS` | no example | bindCredentials for LDAP access | +| | `CMD_LDAP_SEARCHBASE` | `o=users,dc=example,dc=com` | LDAP directory to begin search from | +| | `CMD_LDAP_SEARCHFILTER` | `(uid={{username}})` | LDAP filter to search with | +| | `CMD_LDAP_SEARCHATTRIBUTES` | `displayName, mail` | LDAP attributes to search with (use comma to separate) | +| | `CMD_LDAP_USERIDFIELD` | `uidNumber` or `uid` or `sAMAccountName` | The LDAP field which is used uniquely identify a user on CodiMD | +| | `CMD_LDAP_USERNAMEFIELD` | Fallback to userid | The LDAP field which is used as the username on CodiMD | +| | `CMD_LDAP_TLS_CA` | `server-cert.pem, root.pem` | Root CA for LDAP TLS in PEM format (use comma to separate) | +| | `CMD_LDAP_PROVIDERNAME` | `My institution` | Optional name to be displayed at login form indicating the LDAP provider | + +### Mattermost Login + +| config file | environment | example value | description | +| ------------ | ----------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `mattermost` | | `{baseURL: ..., clientID: ..., clientSecret: ...}` | An object containing the base URL of your Mattermost application data. Refer to the [Mattermost guide](guides/auth/mattermost-self-hosted.md) for more details! | +| | `CMD_MATTERMOST_BASEURL` | no example | Mattermost authentication endpoint for versions below 5.0. For Mattermost version 5.0 and above, see [guide](guides/auth/mattermost-self-hosted.md). | +| | `CMD_MATTERMOST_CLIENTID` | no example | Mattermost API client id | +| | `CMD_MATTERMOST_CLIENTSECRET` | no example | Mattermost API client secret | + +### OAuth2 Login + +| config file | environment | example value | description | +| ----------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `oauth2` | | `{baseURL: ..., userProfileURL: ..., userProfileUsernameAttr: ..., userProfileDisplayNameAttr: ..., userProfileEmailAttr: ..., tokenURL: ..., authorizationURL: ..., clientID: ..., clientSecret: ...}` | An object detailing your OAuth2 provider. Refer to the [Mattermost](guides/auth/mattermost-self-hosted.md) or [Nextcloud](guides/auth/nextcloud.md) examples for more details! | +| | `CMD_OAUTH2_USER_PROFILE_URL` | `https://example.com` | Where to retrieve information about a user after successful login. Needs to output JSON. (no default value) Refer to the [Mattermost](guides/auth/mattermost-self-hosted.md) or [Nextcloud](guides/auth/nextcloud.md) examples for more details on all of the `CMD_OAUTH2...` options. | +| | `CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR` | `name` | where to find the username in the JSON from the user profile URL. (no default value) | +| | `CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR` | `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` | `email` | where to find the email address in the JSON from the user profile URL. (no default value) | +| | `CMD_OAUTH2_TOKEN_URL` | `https://example.com` | sometimes called token endpoint, please refer to the documentation of your OAuth2 provider (no default value) | +| | `CMD_OAUTH2_AUTHORIZATION_URL` | `https://example.com` | authorization URL of your provider, please refer to the documentation of your OAuth2 provider (no default value) | +| | `CMD_OAUTH2_CLIENT_ID` | `afae02fckafd...` | you will get this from your OAuth2 provider when you register CodiMD as OAuth2-client, (no default value) | +| | `CMD_OAUTH2_CLIENT_SECRET` | `afae02fckafd...` | you will get this from your OAuth2 provider when you register CodiMD as OAuth2-client, (no default value) | +| | `CMD_OAUTH2_PROVIDERNAME` | `My institution` | Optional name to be displayed at login form indicating the oAuth2 provider | + +### SAML Login + +| config file | environment | example value | description | +| ----------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `saml` | | `{idpSsoUrl: ..., idpCert: ..., issuer: ..., identifierFormat: ..., disableRequestedAuthnContext: ..., groupAttribute: ..., externalGroups: [], requiredGroups: [], attribute: {id: ..., username: ..., email: ...}}` | An object detailing your SAML provider. Refer to the [OneLogin](guides/auth/saml-onelogin.md) and [SAML](guides/auth/saml.md) guides for more details! | +| | `CMD_SAML_IDPSSOURL` | `https://idp.example.com/sso` | authentication endpoint of IdP. for details, see [guide](guides/auth/saml-onelogin.md). | +| | `CMD_SAML_IDPCERT` | `/path/to/cert.pem` | certificate file path of IdP in PEM format | +| | `CMD_SAML_ISSUER` | no example | Issuer to supply to identity provider (optional, default: `serverURL` config)" | +| | `CMD_SAML_DISABLEREQUESTEDAUTHNCONTEXT` | `true` or `false` | true to allow any authentication method, false restricts to password authentication (PasswordProtectedTransport) method (default: false) | +| | `CMD_SAML_IDENTIFIERFORMAT` | no example | name identifier format (optional, default: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`) | +| | `CMD_SAML_GROUPATTRIBUTE` | `memberOf` | attribute name for group list (optional) | +| | `CMD_SAML_REQUIREDGROUPS` | `codimd-users` | group names that allowed (use vertical bar to separate) (optional) | +| | `CMD_SAML_EXTERNALGROUPS` | `Temporary-staff` | group names that not allowed (use vertical bar to separate) (optional) | +| | `CMD_SAML_ATTRIBUTE_ID` | `sAMAccountName` | attribute map for `id` (optional, default: NameID of SAML response) | +| | `CMD_SAML_ATTRIBUTE_USERNAME` | `mailNickname` | attribute map for `username` (optional, default: NameID of SAML response) | +| | `CMD_SAML_ATTRIBUTE_EMAIL` | `mail` | attribute map for `email` (optional, default: NameID of SAML response if `CMD_SAML_IDENTIFIERFORMAT` is default) | + +### Twitter Login + +| config file | environment | example value | description | +| ----------- | ---------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `twitter` | | `{consumerKey: ..., consumerSecret: ...}` | An object containing the consumer key and secret obtained by the [Twitter developer tools](https://developer.twitter.com/apps). For more details have a look at the [Twitter auth guide](guides/auth/twitter.md) | +| | `CMD_TWITTER_CONSUMERKEY` | no example | Twitter API consumer key | +| | `CMD_TWITTER_CONSUMERSECRET` | no example | Twitter API consumer secret | + +## Upload Storage + +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. + +### Amazon S3 + +| config file | environment | example value | description | +| ----------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `s3` | | `{ "accessKeyId": "YOUR_S3_ACCESS_KEY_ID", "secretAccessKey": "YOUR_S3_ACCESS_KEY", "region": "YOUR_S3_REGION" }` | When `imageuploadtype` be set to `s3`, you would also need to setup this key, check our [S3 Image Upload Guide](guides/s3-image-upload.md) | +| | `CMD_S3_ACCESS_KEY_ID` | no example | AWS access key id | +| | `CMD_S3_SECRET_ACCESS_KEY` | no example | AWS secret key | +| | `CMD_S3_REGION` | `ap-northeast-1` | AWS S3 region | +| `s3bucket` | `CMD_S3_BUCKET` | no example | AWS S3 bucket name | +| | `CMD_S3_ENDPOINT ENV` | no example | S3 API endpoint if you don't use AWS name | + +### Azure Blob Storage + +| config file | environment | example value | description | +| ----------- | ----------------------------- | ------------- | ------------------------------------------------------------------------- | +| | `CMD_AZURE_CONNECTION_STRING` | no example | Azure Blob Storage connection string | +| | `CMD_AZURE_CONTAINER` | no example | Azure Blob Storage container name (automatically created if non existent) | + +### imgur + +| config file | environment | example value | description | +| ----------- | -------------------- | ------------- | ------------------- | +| | `CMD_IMGUR_CLIENTID` | no example | Imgur API client id | + +### Minio + +| config file | environment | example value | description | +| ----------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `minio` | | `{ "accessKey": "YOUR_MINIO_ACCESS_KEY", "secretKey": "YOUR_MINIO_SECRET_KEY", "endpoint": "YOUR_MINIO_HOST", port: 9000, secure: true }` | When `imageUploadType` is set to `minio`, you need to set this key. Also check out our [Minio Image Upload Guide](guides/minio-image-upload.md) | +| | `CMD_MINIO_ACCESS_KEY` | no example | Minio access key | +| | `CMD_MINIO_SECRET_KEY` | no example | Minio secret key | +| | `CMD_MINIO_ENDPOINT` | `minio.example.org` | Address of your Minio endpoint/instance | +| | `CMD_MINIO_PORT` | `9000` | Port that is used for your Minio instance | +| | `CMD_MINIO_SECURE` | `true` | If set to `true` HTTPS is used for Minio | + +### Lutim + +| config file | environment | example value | description | +| ----------- | --------------- | --------------------------- | --------------------------------------------------------------------------- | +| `lutim` | | `{"url": "YOUR_LUTIM_URL"}` | When `imageUploadType` is set to `lutim`, you can setup the lutim url | +| | `CMD_LUTIM_URL` | `https://framapic.org/` | When `CMD_IMAGE_UPLOAD_TYPE` is set to `lutim`, you can setup the lutim url | diff --git a/docs/setup/manual-setup.md b/docs/setup/manual-setup.md index 4aad56a6..3979cebc 100644 --- a/docs/setup/manual-setup.md +++ b/docs/setup/manual-setup.md @@ -18,16 +18,15 @@ Manual Installation 1. Check if you meet the [requirements at the top of this document](#requirements-on-your-server). 2. Clone this repository (preferred) or download a release and unzip it. 3. Enter the directory and type `bin/setup`, which will install npm dependencies and create configs. -4. Modify `config.json`, see docs [here](https://github.com/codimd/server/blob/master/docs/configuration-config-file.md). -5. Instead of modifying `config.json`, it's possible to configure CodiMD through environment variables which will - overwrite the configs, see docs [here](https://github.com/codimd/server/blob/master/docs/configuration-env-vars.md). -6. Build front-end bundle by `yarn run build` (use `yarn run dev` if you are in development) -7. Modify the file named `.sequelizerc`, change the value of the variable `url` with your db connection string. For example: +4. Modify `config.json` or configure CodiMD through environment variables which will + overwrite the configs, see docs [here](https://github.com/codimd/server/blob/master/docs/configuration.md). +5. Build front-end bundle by `yarn run build` (use `yarn run dev` if you are in development) +6. Modify the file named `.sequelizerc`, change the value of the variable `url` with your db connection string. For example: - `postgres://username:password@localhost:5432/codimd` - `mysql://username:password@localhost:3306/codimd` - `sqlite://:memory:` -8. It is recommended to start your server manually once: `npm start --production`, this way it's easier to see warnings or errors that might occur (leave out `--production` for development). -9. Run the server as you like (node, forever, pm2, SystemD, Init-Scripts) +7. It is recommended to start your server manually once: `npm start --production`, this way it's easier to see warnings or errors that might occur (leave out `--production` for development). +8. Run the server as you like (node, forever, pm2, SystemD, Init-Scripts) ## How to upgrade your installation |