github/hedgedoc
1
0
Fork 0
mirror of https://github.com/hedgedoc/hedgedoc.git synced 2024-11-25 03:06:31 -05:00
Code Issues Projects Releases Packages Wiki Activity

Docs: Add configuration documentation

Browse source 
This adds documentation for the configuration of HedgeDoc.

Signed-off-by: Philip Molares <philip.molares@udo.edu>
This commit is contained in:
Philip Molares 2021-04-25 17:29:53 +02:00
parent 44ea7604d8
commit 0512308159
7 changed files with 92 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

83
docs/content/config/index.md Normal file
View file

@ -0,0 +1,83 @@
HedgeDoc can be configured via environment variables either directly or via an `.env` file.
## The `.env` file
The `.env` file should be placed in the root of the project and contains key-value pairs of environment variables and their corresponding value. This can for example look like this:
```ini
HD_DOMAIN="http://localhost"
HD_MEDIA_BACKEND="filesystem"
HD_MEDIA_BACKEND_FILESYSTEM_UPLOAD_PATH="uploads/"
HD_DATABASE_DIALECT="sqlite"
HD_DATABASE_STORAGE="./hedgedoc.sqlite"
```
We also provide an `.env.example` file containing a minimal configuration in the root of the project. This should help you to write your own configuration.
!!! warning
The minimal configuration provided in `.env.example` is exactly that: minimal. It will let you start HedgeDoc, but it is **not** meant to be used in production without prior changes.
## General
| environment variable | default | example | description |
|--------------------------|-----------|------------------------------|---------------------------------------------------------------------------------------------------|
| `HD_DOMAIN` | - | `https://md.example.com` | The URL the HedgeDoc instance runs on. |
| `PORT` | 3000 | | The port the HedgeDoc instance runs on. |
| `HD_RENDERER_ORIGIN` | HD_DOMAIN | | The URL the renderer runs on. If omitted this will be same as `HD_DOMAIN`. |
| `HD_LOGLEVEL` | warn | | The loglevel that should be used. Options are `error`, `warn`, `info`, `debug` or `trace`. |
| `HD_FORBIDDEN_NOTE_IDS` | - | `notAllowed, alsoNotAllowed` | A list of note ids (separated by `,`), that are not allowed to be created or requested by anyone. |
| `HD_MAX_DOCUMENT_LENGTH` | 100000 | | The maximum length of any one document. Changes to this will impact performance for your users. |
### Why should I want to run my renderer on a different (sub-)domain?
If the renderer is provided by another domain, it's way harder to manipulate HedgeDoc or steal credentials from the rendered note content, because renderer and editor are more isolated. This increases the security of the software and greatly mitigates [XSS attacks](https://en.wikipedia.org/wiki/Cross-site_scripting). However, you can run HedgeDoc without this extra security, but we recommend using it if possible.
## Authentication
**ToDo:** Add Authentication docs
## Customization
| environment variable | default | example | description |
|-----------------------|---------|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `HD_CUSTOM_NAME` | - | `DEMO Corp` | The text will be shown in the top right corner in the editor and on the intro page. If you also configure a custom logo, this will be used as the alt text of the logo. |
| `HD_CUSTOM_LOGO` | - | `https://md.example.com/logo.png` | The logo will be shown in the top right corner in the editor and on the intro page. |
| `HD_PRIVACY_URL` | - | `https://md.example.com/privacy` | The URL that should be linked as the privacy notice in the footer. |
| `HD_TERMS_OF_USE_URL` | - | `https://md.example.com/terms` | The URL that should be linked as the terms of user in the footer. |
| `HD_IMPRINT_URL` | - | `https://md.example.com/imprint` | The URL that should be linked as the imprint in the footer. |
**ToDo:** Add screenshots to illustrate custom name and custom logo.
## Database
We officially support and test these databases:
- SQLite (for development and smaller instances)
- PostgreSQL
- MariaDB
| environment variable | default | example | description |
|------------------------|---------|---------------------|-----------------------------------------------------------------------------------------------|
| `HD_DATABASE_DIALECT` | - | `postgres` | The database dialect you want to use. This can be `postgres`, `mysql`, `mariadb` or `sqlite`. |
| `HD_DATABASE_HOST` | - | `db.example.com` | The host, where the database runs. *Only if you're **not** using `sqlite`.* |
| `HD_DATABASE_PORT` | - | `5432` | The port, where the database runs. *Only if you're **not** using `sqlite`.* |
| `HD_DATABASE_NAME` | - | `hedgedoc` | The name of the database to use. *Only if you're **not** using `sqlite`.* |
| `HD_DATABASE_USER` | - | `hedgedoc` | The user that logs in the database. *Only if you're **not** using `sqlite`.* |
| `HD_DATABASE_PASS` | - | `password` | The password to log into the database. *Only if you're **not** using `sqlite`.* |
| `HD_DATABASE_STORAGE` | - | `./hedgedoc.sqlite` | The location of the database file. *Only if you're using `sqlite`.* |
## External services
| environment variable | default | example | description |
|------------------------|---------|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| `HD_PLANTUML_SERVER` | - | `https://www.plantuml.com/plantuml` | The PlantUML server that HedgeDoc uses to render PlantUML diagrams. If this is not configured, PlantUML diagrams won't be rendered. |
| `HD_IMAGE_PROXY` | - | `https://image-proxy.example.com` | **ToDo:** Add description |
## Media
There are couple of different backends that can be used to host your images for HedgeDoc.
- [Azure](media/azure.md)
- [Local filesystem](media/filesystem.md)
- [Imgur](media/imgur.md)
- [S3-compatible](media/s3.md)
- [WebDAV](media/webdav.md)

0
docs/content/media/azure.md → docs/content/config/media/azure.md
View file

2
docs/content/media/filesystem.md → docs/content/config/media/filesystem.md
View file

@ -9,4 +9,4 @@ HD_MEDIA_BACKEND="filesystem"
HD_MEDIA_BACKEND_FILESYSTEM_UPLOAD_PATH="<DIRECTORY>"
```
Please make sure that the user that runs HedgeDoc is able to write to the uploads directory.
Please make sure that the user that runs HedgeDoc is able to write to the `uploads` directory.

0
docs/content/media/imgur.md → docs/content/config/media/imgur.md
View file

0
docs/content/media/s3.md → docs/content/config/media/s3.md
View file

0
docs/content/media/webdav.md → docs/content/config/media/webdav.md
View file

8
docs/mkdocs.yml
View file

@ -7,6 +7,14 @@ docs_dir: content
edit_uri: https://github.com/hedgedoc/hedgedoc/edit/master/docs/content/
nav:
- Home: index.md
- Configuration:
- Configuration: config/index.md
- Media:
- Azure: config/media/azure.md
- Filesystem: config/media/filesystem.md
- imgur: config/media/imgur.md
- S3: config/media/s3.md
- WebDAV: config/media/webdav.md
- Interface:
Toolbar: interface/toolbar.md
- References: