mirrors/hedgedoc
1
0
Fork 0
mirror of https://github.com/hedgedoc/hedgedoc.git synced 2025-05-18 17:25:16 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

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 • committed by David Mehren
parent 7ef3e4a1f1
commit 9c2e47dcc4
No known key found for this signature in database
GPG key ID: 185982BA4C42B7C3
7 changed files with 92 additions and 1 deletions
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)

21
docs/content/config/media/azure.md Normal file
View file

@ -0,0 +1,21 @@
# Azure Blob Storage
You can use [Microsoft Azure Blob Storage](https://azure.microsoft.com/services/storage/blobs/) to handle your image uploads in HedgeDoc.
All you need to do is to get the [connection string](https://docs.microsoft.com/azure/storage/common/storage-account-keys-manage) for your storage account and create a storage container with public access set to 'blob'.
It's possible to create the container with the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli), using your connection string, with the following command:
```
az storage container create --name <NAME> --public-access blob --connection-string "<CONNECTION_STRING>"
```
You can of course also create the container in the Azure portal if you prefer.
Then you just add the following lines to your configuration:
<small>(with the appropriate substitution for `<CONNECTION_STRING>` and `<NAME>` of course)</small>
```
HD_MEDIA_BACKEND="azure"
HD_MEDIA_BACKEND_AZURE_CONNECTION_STRING="<CONNECTION_STRING>"
HD_MEDIA_BACKEND_AZURE_CONTAINER="<NAME>"
```

12
docs/content/config/media/filesystem.md Normal file
View file

@ -0,0 +1,12 @@
# Filesystem
You can use your local filesystem to handle your image uploads in HedgeDoc.
You just add the following lines to your configuration:
<small>(with the appropriate substitution for `<DIRECTORY>` of course)</small>
```
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.

19
docs/content/config/media/imgur.md Normal file
View file

@ -0,0 +1,19 @@
# Imgur
You can use [Imgur](https://imgur.com) to handle your image uploads in HedgeDoc.
All you need for that is to register an application with Imgur and get a client id:
1. Create an account on imgur.com and log in.
2. Go to <https://api.imgur.com/oauth2/addclient>
3. Fill out the form and choose "Anonymous usage without user authorization" as the authorization type.
4. Imgur will then show you your client id.
Then you just add the following lines to your configuration:
<small>(with the appropriate substitution for `<IMGUR_CLIENT_ID>` of course)</small>
```
HD_MEDIA_BACKEND="imgur"
HD_MEDIA_BACKEND_IMGUR_CLIENT_ID="<IMGUR_CLIENT_ID>"
```
All uploads are saved in the `media_uploads` database table and contain the deletion token ([see here](https://apidocs.imgur.com/#949d6cb0-5e55-45f7-8853-8c44a108399c)) in the column `backendData`.

19
docs/content/config/media/s3.md Normal file
View file

@ -0,0 +1,19 @@
# S3-compatible
You can use [Amazon S3](https://aws.amazon.com/s3/) or any other S3-compatible storage (like [MinIO](https://min.io) or [Ceph Object Gateway](https://docs.ceph.com/en/latest/radosgw/)) to handle your image uploads in HedgeDoc.
Your S3 bucket must be configured to be writeable.
You just add the following lines to your configuration:
<small>(with the appropriate substitution for `<ACCESS_KEY>`, `<SECRET_KEY>`, `<BUCKET>`, and `<ENDPOINT>` of course)</small>
```
HD_MEDIA_BACKEND="s3"
HD_MEDIA_BACKEND_S3_ACCESS_KEY="<ACCESS_KEY>"
HD_MEDIA_BACKEND_S3_SECRET_KEY="<SECRET_KEY>"
HD_MEDIA_BACKEND_S3_BUCKET="<BUCKET>"
HD_MEDIA_BACKEND_S3_ENDPOINT="<ENDPOINT>"
```
If you use Amazon S3, `<ENDPOINT>` should contain your [Amazon Region](https://docs.aws.amazon.com/general/latest/gr/s3.html).
For example: If your Amazon Region is `us-east-2`, your endpoint `<ENDPOINT>` should be `s3.us-east-2.amazonaws.com`.

46
docs/content/config/media/webdav.md Normal file
View file

@ -0,0 +1,46 @@
# WebDAV
You can use any [WebDAV](https://en.wikipedia.org/wiki/WebDAV) server to handle your image uploads in HedgeDoc.
The WebDAV server must host the files in a way that allows HedgeDoc to request and receive them.
You just add the following lines to your configuration:
<small>(with the appropriate substitution for `<CONNECTION_STRING>`, `<UPLOAD_DIR>`, and `<PUBLIC_URL>` of course)</small>
```
HD_MEDIA_BACKEND="webdav"
HD_MEDIA_BACKEND_WEBDAV_CONNECTION_STRING="<CONNECTION_STRING>"
HD_MEDIA_BACKEND_WEBDAV_UPLOAD_DIR="<UPLOAD_DIR>"
HD_MEDIA_BACKEND_WEBDAV_PUBLIC_URL="<PUBLIC_URL>"
```
The `<CONNECTION_STRING>` should include the username and password (if needed) in the familiar way of `schema://user:password@url`.
With `<UPLOAD_DIR>` you can specify a folder you want to upload to, but you can also omit this (just don't spcify this value at all), if you prefer to upload directly to the root of the WebDAV server.
Finally, `<PUBLIC_URL>` specifies with which url HedgeDoc can access the upload. For this purpose the filename will be appended to `<PUBLIC_URL>`. So the file `test.png` with `<PUBLIC_URL>` `https://dav.example.com` should be accessible via `https://dav.example.com/test.png`.
## Using Nextcloud
If you want to use Nextcloud as a WebDAV server, follow the following instructions:
This guide was written using Nextcloud 21 in April 2021.
Because the username and app password will be included in the config, we suggest using a dedicated Nextcloud user for the uploads.
In this example the username will be `TestUser`.
1. Create an app password by going to `Settings` > `Security`. Nextcloud will generate a password for you. Let's assume it's `passw0rd`.
2. In the Files app [create a new folder](https://docs.nextcloud.com/server/latest/user_manual/en/files/access_webgui.html#creating-or-uploading-files-and-directories) that will hold your uploads (e.g `HedgeDoc`).
3. [Share](https://docs.nextcloud.com/server/latest/user_manual/en/files/sharing.html#public-link-shares) the newly created folder. The folder should (per default) be configured with the option `Read Only` (which we will assume in this guide), but `Allow upload and editing` should be fine, too.
4. Get the public link of the share. It should be in your clipboard after creation. If not you can copy it by clicking the clipboard icon at the end of the line of `Share link`. We'll assume it is `https://cloud.example.com/s/some-id` in the following.
5. Append `/download?path=%2F&files=` to this URL. To continue with our example the url should now be `https://cloud.example.com/s/some-id/download?path=%2F&files=`.
6. Get the [WebDAV url of you Nextcloud server](https://docs.nextcloud.com/server/latest/user_manual/en/files/access_webdav.html). It should be located in the Files app in the bottom left corner under `Settings` > `WebDAV`. We'll assume it is `https://cloud.example.com/remote.php/dav/files/TestUser/` in the following.
7. Add your login information to the link. This is done by adding `username:password@` in between the url schema (typically `https://`) and the rest of the url (`cloud.example.com/remote.php/dav/files/TestUser/` in our example). The WebDAV url in our example should now look like this `https://TestUser:passw0rd@cloud.example.com/remote.php/dav/files/TestUser/`.
8. Configure HedgeDoc:
```
HD_MEDIA_BACKEND="webdav"
HD_MEDIA_BACKEND_WEBDAV_CONNECTION_STRING="https://TestUser:passw0rd@cloud.example.com/remote.php/dav/files/TestUser/"
HD_MEDIA_BACKEND_WEBDAV_UPLOAD_DIR="HedgeDoc"
HD_MEDIA_BACKEND_WEBDAV_PUBLIC_URL="https://cloud.example.com/s/some-id/download?path=%2F&files="
```
Start using image uploads backed by Nextclouds WebDAV server.