From 7cdb40585ee6f02b6b44c8f4c998875b5164c11f Mon Sep 17 00:00:00 2001 From: Philip Molares Date: Wed, 3 Feb 2021 20:50:49 +0100 Subject: [PATCH 1/3] Dev Docs: Add configuration documentation This explains how the configuration code works and give some hints on what do look out for while working on the configuration code. Signed-off-by: Philip Molares --- docs/content/dev/config.md | 74 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/content/dev/config.md diff --git a/docs/content/dev/config.md b/docs/content/dev/config.md new file mode 100644 index 000000000..5e9e36eb5 --- /dev/null +++ b/docs/content/dev/config.md @@ -0,0 +1,74 @@ +# Config + +The configuration of HedgeDoc is handled entirely by environment variables. Most of these variables are prefixed with `HD_` (for HedgeDoc). + +## Configuring HedgeDoc for development + +NestJS - the framework we use - is reading the variables from the environment and also from the `.env` file in the root of the project. To make it easy to get the project started we included an example `.env` file in the root of this project called `.env.example`. + +## How the config code works + +The config of HedgeDoc is split up into **six** different modules: + +`app.config.ts` +: General configuration of the app + +`auth.config.ts` +: Which authentication providers are available and which options are set + +`csp.config.ts` +: Configuration for [Content Security Policy][csp] + +`database.config.ts` +: Which database should be used + +`hsts.config.ts` +: Configuration for [HTTP Strict-Transport-Security][hsts] + +`media.config.ts` +: Where media files are being stored + +Each of those files (except `auth.config.ts` which is discussed later) consists of three parts: + +1. An Interface +2. A Joi schema +3. A default export + +### Interface + +The interface just describes what options the configuration has and how the rest of HedgeDoc can use them. All enums that are used in here are put in their own files with the extension `.enum.ts`. + +### Joi Schema + +We use [Joi][joi] to validate each provided configuration to make sure the configuration of the user is sound and provide helpful error messages if that's not the case. + +The most important part here is that each value has a `.label()` at the end. With this the environment variable name that corresponds to each config option is described. It's very important that each config options is given the correct label to have meaningful error messages that benefit the user. + +Everything else about how Joi works and how you should write schemas can be read in [their documentation][joi-doc]. + +### A default export + +The default exports are used by NestJS to provide the values to the rest of the application. We mostly do four things here: + +1. Populate the config interface with environment variables, creating the config object. +2. Validate the config object against the Joi schema. +3. Work on the error messages from Joi and present them to the user (if any occur). +4. Return the validated config object. + +## How `auth.config.ts` works + +Because it's possible to configure some authentication provider more than once (multiple LDAPs, multiple GitLabs) and we don't know how many, we use user defined environment variable names. With the user defined names it's not possible to put the correct labels in the schema or build the config objects as we do in every other file. + +Therefore, we have two big extra steps in the default export: +1. To populate the config object we have some code at the top of the default export to gather all configured variables into arrays. +2. The error messages are piped into the util method `replaceAuthErrorsWithEnvironmentVariables`. This replaces the error messages of the form `gitlab[0].providerName` with `HD_AUTH_GITLAB__PROVIDER_NAME`. For this the util functions gets the error, the name of the config option (e.g `'gitlab'`), the approriate prefix (e.g. `'HD_AUTH_GITLAB_'`), and an array of the user defined names. + +## Mocks + +Some config files also have a `.mock.ts` file in which the configuration for the e2e tests is defined. Those files just contain the default export and returns the mock config object. + + +[csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP +[hsts]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security +[joi]: https://joi.dev/ +[joi-doc]: https://joi.dev/api From c593965d5a9224863922d5b966680868021a071a Mon Sep 17 00:00:00 2001 From: Philip Molares Date: Wed, 3 Feb 2021 20:51:36 +0100 Subject: [PATCH 2/3] Dev Docs: Add .env.example file This file contains a minimal working config to get the backend up and running. Signed-off-by: Philip Molares --- .env.example | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .env.example diff --git a/.env.example b/.env.example new file mode 100644 index 000000000..9500681fe --- /dev/null +++ b/.env.example @@ -0,0 +1,5 @@ +HD_DOMAIN="http://localhost" +HD_MEDIA_BACKEND="filesystem" +HD_MEDIA_BACKEND_FILESYSTEM_UPLOAD_PATH="upload/" +HD_DATABASE_DIALECT="sqlite" +HD_DATABASE_STORAGE="./hedgedoc.sqlite" From c0e797bca6ec3ab42f7c19667e70f7b64aa8d3b2 Mon Sep 17 00:00:00 2001 From: Philip Molares Date: Wed, 3 Feb 2021 20:58:16 +0100 Subject: [PATCH 3/3] Dev Docs: Add configuration to navigation This makes it possible to access the developer documentation about configuration code. Signed-off-by: Philip Molares --- .env.example | 4 ++++ docs/content/dev/config.md | 17 ++++++++--------- docs/mkdocs.yml | 1 + 3 files changed, 13 insertions(+), 9 deletions(-) diff --git a/.env.example b/.env.example index 9500681fe..42ccd4f8d 100644 --- a/.env.example +++ b/.env.example @@ -1,3 +1,7 @@ +# SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file) +# +# SPDX-License-Identifier: CC0-1.0 + HD_DOMAIN="http://localhost" HD_MEDIA_BACKEND="filesystem" HD_MEDIA_BACKEND_FILESYSTEM_UPLOAD_PATH="upload/" diff --git a/docs/content/dev/config.md b/docs/content/dev/config.md index 5e9e36eb5..c799bc1d2 100644 --- a/docs/content/dev/config.md +++ b/docs/content/dev/config.md @@ -30,19 +30,19 @@ The config of HedgeDoc is split up into **six** different modules: Each of those files (except `auth.config.ts` which is discussed later) consists of three parts: -1. An Interface +1. An interface 2. A Joi schema 3. A default export ### Interface -The interface just describes what options the configuration has and how the rest of HedgeDoc can use them. All enums that are used in here are put in their own files with the extension `.enum.ts`. +The interface just describes which options the configuration has and how the rest of HedgeDoc can use them. All enums that are used in here are put in their own files with the extension `.enum.ts`. ### Joi Schema -We use [Joi][joi] to validate each provided configuration to make sure the configuration of the user is sound and provide helpful error messages if that's not the case. +We use [Joi][joi] to validate each provided configuration to make sure the configuration of the user is sound and provides helpful error messages otherwise. -The most important part here is that each value has a `.label()` at the end. With this the environment variable name that corresponds to each config option is described. It's very important that each config options is given the correct label to have meaningful error messages that benefit the user. +The most important part here is that each value ends with `.label()`. This names the environment variable that corresponds to each config option. It's very important that each config option is assigned the correct label to have meaningful error messages that benefit the user. Everything else about how Joi works and how you should write schemas can be read in [their documentation][joi-doc]. @@ -52,21 +52,20 @@ The default exports are used by NestJS to provide the values to the rest of the 1. Populate the config interface with environment variables, creating the config object. 2. Validate the config object against the Joi schema. -3. Work on the error messages from Joi and present them to the user (if any occur). +3. Polish the error messages from Joi and present them to the user (if any occur). 4. Return the validated config object. ## How `auth.config.ts` works -Because it's possible to configure some authentication provider more than once (multiple LDAPs, multiple GitLabs) and we don't know how many, we use user defined environment variable names. With the user defined names it's not possible to put the correct labels in the schema or build the config objects as we do in every other file. +Because it's possible to configure some authentication providers multiple times (e.g. multiple LDAPs or GitLabs), we use user defined environment variable names. With the user defined names it's not possible to put the correct labels in the schema or build the config objects as we do in every other file. Therefore, we have two big extra steps in the default export: 1. To populate the config object we have some code at the top of the default export to gather all configured variables into arrays. -2. The error messages are piped into the util method `replaceAuthErrorsWithEnvironmentVariables`. This replaces the error messages of the form `gitlab[0].providerName` with `HD_AUTH_GITLAB__PROVIDER_NAME`. For this the util functions gets the error, the name of the config option (e.g `'gitlab'`), the approriate prefix (e.g. `'HD_AUTH_GITLAB_'`), and an array of the user defined names. +2. The error messages are piped into the util method `replaceAuthErrorsWithEnvironmentVariables`. This replaces the error messages of the form `gitlab[0].providerName` with `HD_AUTH_GITLAB__PROVIDER_NAME`. For this the util function gets the error, the name of the config option (e.g `'gitlab'`), the approriate prefix (e.g. `'HD_AUTH_GITLAB_'`), and an array of the user defined names. ## Mocks -Some config files also have a `.mock.ts` file in which the configuration for the e2e tests is defined. Those files just contain the default export and returns the mock config object. - +Some config files also have a `.mock.ts` file which defines the configuration for the e2e tests. Those files just contain the default export and return the mock config object. [csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP [hsts]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b764e45eb..f6b7cb167 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -9,6 +9,7 @@ nav: - Home: index.md - Developer: - '2.0 Development': dev/2.0.md + - Configuration: dev/config.md - 'Documentation': dev/documentation.md - FAQ: https://hedgedoc.org/faq markdown_extensions: