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

docs: restructure

Browse source
This commit is contained in:
Erik Michelson 2025-02-11 18:00:04 +01:00 • committed by Erik Michelson
parent 91ebd519a8
commit 70a6583fe0
No known key found for this signature in database
GPG key ID: DB99ADDDC5C0AF82
69 changed files with 471 additions and 385 deletions
Download patch file Download diff file Expand all files Collapse all files

56
docs/content/config/auth/index.md Normal file
View file

@ -0,0 +1,56 @@
# Authentication
HedgeDoc supports multiple authentication mechanisms that can be enabled and configured.
An authentication method is always linked to an account on the HedgeDoc instance.
However, an account can also have multiple authentication methods linked.
Each user has a unique username.
By this username, other users can invite them to their notes.
When first logging in with a new authentication method, a new account will be created.
If a user already has an account, they can link a new authentication method in their settings.
## Supported authentication methods
- [Username and password (Local account)](./local.md)
- [LDAP](./ldap.md)
- [OpenID Connect (OIDC)](./oidc.md)
While HedgeDoc provides a basic local account system, we recommend using an external
authentication mechanism for most environments.
For LDAP and OIDC you can configure multiple auth providers of that type.
You need to give each of them a unique identifier that is used in the configuration
and in the database.
The identifier should consist of only letters (`a-z`, `A-Z`), numbers (`0-9`), and dashes (`-`).
## Profile sync
A HedgeDoc account stores generic profile information like the display name of the
user and optionally a URL to a profile picture.
Depending on your configuration, users can change this information in their settings.
You can also configure HedgeDoc to sync this information from an external source like
LDAP or OIDC. In this case, changes made by the user will be overridden on login with
the external source, that is configured as sync source.
## Account merging
There's no built-in account merging in HedgeDoc. So if you registered with different
auth methods, you will have different accounts.
To manually resolve this situation, you can do the following:
1. Log in with the second account (this should be merged into the first one).
2. Visit every note, you own on that account and change the note ownership to your first account.
3. Ensure, there's nothing left anymore. Then delete the second account.
4. Log in with the first account.
5. Link the auth method of the former second account to your account in the settings.
## Common configuration
| environment variable | default | example | description |
|---------------------------------|-----------|---------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `HD_SESSION_SECRET` | (not set) | `5aaea9250828ce6942b35d170a385e74c41f1f05`, just random data | **Required.** The secret used to sign the session cookie. |
| `HD_SESSION_LIFETIME` | `1209600` | `604800`, `1209600` | The lifetime of a session in seconds. After this time without activity, a user will be logged out. |
| `HD_AUTH_ALLOW_PROFILE_EDITS` | `true` | `true`, `false` | Allow users to edit their profile information. |
| `HD_AUTH_ALLOW_CHOOSE_USERNAME` | `true` | `true`, `false` | If enabled, users may freely choose their username when signing-up via an external auth source (OIDC). Otherwise the username from the external auth source is taken. |
| `HD_AUTH_SYNC_SOURCE` | (not set) | `gitlab`, if there's an auth method (LDAP or OIDC) with the identifier `gitlab` | If enabled, the auth method with the configured identifier will update user's profile information on login. |

27
docs/content/config/auth/ldap.md Normal file
View file

@ -0,0 +1,27 @@
# LDAP
HedgeDoc can use one or multiple LDAP servers to authenticate users. To do this, you
first need to tell HedgeDoc identifiers for the servers you want to use (`HD_AUTH_LDAP_SERVERS`).
Then you need to provide the configuration for these LDAP servers
depending on how you want to use them.
Each of these variables will contain the identifier for the LDAP server.
For example, if you chose the identifier `MYLDAP` for your LDAP server, all variables
for this server will start with `HD_AUTH_LDAP_MYLDAP_`.
Replace `$NAME` with the identifier of the LDAP server in the table below accordingly.
| environment variable | default | example | description |
|--------------------------------------------|----------------------|----------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| `HD_AUTH_LDAP_SERVERS` | - | `MYLDAP` | A comma-seperated list of names of LDAP servers HedgeDoc should use. |
| `HD_AUTH_LDAP_$NAME_PROVIDER_NAME` | `LDAP` | `My LDAP` | The display name for the LDAP server, that is shown in the UI of HegdeDoc. |
| `HD_AUTH_LDAP_$NAME_URL` | - | `ldaps://ldap.example.com` | The url with which the LDAP server can be accessed. |
| `HD_AUTH_LDAP_$NAME_SEARCH_BASE` | - | `ou=users,dc=LDAP,dc=example,dc=com` | The LDAP search base which contains the user accounts on the LDAP server. |
| `HD_AUTH_LDAP_$NAME_SEARCH_FILTER` | `(uid={{username}})` | `(&(uid={{username}})(objectClass=inetOrgPerson))` | A LDAP search filter that filters the users that should have access. |
| `HD_AUTH_LDAP_$NAME_SEARCH_ATTRIBUTES` | - | `username,cn` | A comma-seperated list of attributes that the search filter from the LDAP server should access. |
| `HD_AUTH_LDAP_$NAME_USER_ID_FIELD` | `uid` | `uid`, `uidNumber`, `sAMAccountName` | The attribute of the user account which should be used as an id for the user. |
| `HD_AUTH_LDAP_$NAME_DISPLAY_NAME_FIELD` | `displayName` | `displayName`, `name`, `cn` | The attribute of the user account which should be used as the display name for the user. |
| `HD_AUTH_LDAP_$NAME_PROFILE_PICTURE_FIELD` | `jpegPhoto` | `jpegPhoto`, `thumbnailPhoto` | The attribute of the user account which should be used as the user image for the user. |
| `HD_AUTH_LDAP_$NAME_BIND_DN` | - | `cn=admin,dc=LDAP,dc=example,dc=com` | The dn which is used to perform the user search. If this is omitted then HedgeDoc will use an anonymous bind. |
| `HD_AUTH_LDAP_$NAME_BIND_CREDENTIALS` | - | `MyLdapPassword` | The credential to access the LDAP server. |
| `HD_AUTH_LDAP_$NAME_TLS_CERT_PATHS` | - | `LDAP-ca.pem` | A comma-seperated list of paths to TLS certificates for the LDAP server. |

25
docs/content/config/auth/local.md Normal file
View file

@ -0,0 +1,25 @@
# Local
HedgeDoc provides local accounts, handled internally. This feature only provides basic
functionality, so for most environments, we recommend using an external authentication mechanism,
which also enables more secure authentication like 2FA or Passkeys.
| environment variable | default | example | description |
|-------------------------------------------|---------|-------------------------|-----------------------------------------------------------------------------------------------------|
| `HD_AUTH_LOCAL_ENABLE_LOGIN` | `false` | `true`, `false` | This makes it possible to use the local accounts in HedgeDoc. |
| `HD_AUTH_LOCAL_ENABLE_REGISTER` | `false` | `true`, `false` | This makes it possible to register new local accounts in HedgeDoc. |
| `HD_AUTH_LOCAL_MINIMAL_PASSWORD_STRENGTH` | `2` | `0`, `1`, `2`, `3`, `4` | The minimum password score, that passwords need to have. See the table below for more explanations. |
## Password score
The password score is calculated with [zxcvbn-ts][zxcvbn-ts-score].
| score | meaning | minimum number of guesses required (approximated) |
|:-----:|-------------------------------------------------------------------|---------------------------------------------------|
| 0 | All passwords with minimum 6 characters are allowed | - |
| 1 | Only `too guessable` passwords are disallowed | 1.000 |
| 2 | `too guessable` and `very guessable` passwords are disallowed | 1.000.000 |
| 3 | `safely unguessable` and `very unguessable` passwords are allowed | 100.000.000 |
| 4 | Only `very unguessable` passwords are allowed | 10.000.000.000 |
[zxcvbn-ts-score]: https://zxcvbn-ts.github.io/zxcvbn/guide/getting-started/#output

70
docs/content/config/auth/oidc.md Normal file
View file

@ -0,0 +1,70 @@
# OpenID Connect (OIDC)
HedgeDoc can use one or multiple OIDC servers to authenticate users. To do this, you first need
to tell HedgeDoc identifiers for the servers you want to use (`HD_AUTH_OIDC_SERVERS`). Then you
need to provide the configuration for these OIDC servers depending on how you want to use them.
Each of these variables will contain the identifier for the OIDC server.
For example, if you chose the identifier `MYOIDC` for your OIDC server, all variables
for this server will start with `HD_AUTH_OIDC_MYOIDC_`.
Replace `$NAME` with the identifier of the OIDC server in the table below accordingly.
| environment variable | default | example | description |
|--------------------------------------|------------------|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| `HD_AUTH_OIDC_SERVERS` | - | `MYOIDC` | A comma-seperated list of identifiers of OIDC servers HedgeDoc should use. |
| `HD_AUTH_OIDC_$NAME_PROVIDER_NAME` | `OpenID Connect` | `My OIDC Single-Sign-On` | The display name for the OIDC server, that is shown in the UI of HegdeDoc. |
| `HD_AUTH_OIDC_$NAME_ISSUER` | - | `https://auth.example.com` | The base url of the OIDC issuer. It should serve a file `.well-known/openid-configuration` |
| `HD_AUTH_OIDC_$NAME_CLIENT_ID` | - | `hd2` | The id with which HedgeDoc is registered at the OIDC server. |
| `HD_AUTH_OIDC_$NAME_CLIENT_SECRET` | - | `c3f70208375cf26700920678ec55b7df7cd75266` | The secret for the HedgeDoc application, given by the OIDC server. |
| `HD_AUTH_OIDC_$NAME_THEME` | - | `gitlab`, `google`, ... | The theme in which the button on the login page should be displayed. See below for a list of options. If not defined, a generic one will be used. |
| `HD_AUTH_OIDC_$NAME_ENABLE_REGISTER` | `true` | `true`, `false` | If set to `false`, only users that already exist in the HedgeDoc server are able to login. |
As redirect URL you should configure
`https://hedgedoc.example.com/api/private/auth/oidc/$NAME/callback` where `$NAME`
is the identifier of the OIDC server. Remember to update the domain to your one.
You can also configure servers that only support plain OAuth2 but
no OIDC (e.g., GitHub or Discord). In this case, you need the following additional variables:
| environment variable | default | example | description |
|--------------------------------------------|----------------------|--------------------------------------------|------------------------------------------------------------------------------------------|
| `HD_AUTH_OIDC_$NAME_AUTHORIZE_URL` | - | `https://auth.example.com/oauth2/auth` | The URL to which the user should be redirected to start the OAuth2 flow. |
| `HD_AUTH_OIDC_$NAME_TOKEN_URL` | - | `https://auth.example.com/oauth2/token` | The URL to which the user should be redirected to exchange the code for an access token. |
| `HD_AUTH_OIDC_$NAME_USERINFO_URL` | - | `https://auth.example.com/oauth2/userinfo` | The URL to which the user should be redirected to get the user information. |
| `HD_AUTH_OIDC_$NAME_END_SESSION_URL` | - | `https://auth.example.com/oauth2/logout` | The URL to which the user should be redirected to end the session. |
| `HD_AUTH_OIDC_$NAME_SCOPE` | - | `profile` | The scope that should be requested to get the user information. |
| `HD_AUTH_OIDC_$NAME_USER_ID_FIELD` | `sub` | `sub`, `id` | The unique identifier that is returned for the user from the OAuth2 provider. |
| `HD_AUTH_OIDC_$NAME_USER_ID_FIELD` | `sub` | `sub`, `id` | The unique identifier that is returned for the user from the OAuth2 provider. |
| `HD_AUTH_OIDC_$NAME_USER_NAME_FIELD` | `preferred_username` | `preferred_username`, `username` | The unique identifier that is returned for the user from the OAuth2 provider. |
| `HD_AUTH_OIDC_$NAME_DISPLAY_NAME_FIELD` | `name` | `name`, `displayName` | The field that contains the display name of the user. |
| `HD_AUTH_OIDC_$NAME_PROFILE_PICTURE_FIELD` | - | `picture`, `avatar` | The field that contains the URL to the profile picture of the user. |
| `HD_AUTH_OIDC_$NAME_EMAIL_FIELD` | `email` | `email`, `mail` | The field that contains the email address of the user. |
## Themes
To integrate the brand colors and icons of some popular OIDC providers into the login button,
you can use one of the following values:
- `google`
- `github`
- `gitlab`
- `facebook`
- `discord`
- `mastodon`
- `azure`
## Common providers
| Provider | support | issuer variable | Docs |
|-----------|-------------|---------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|
| Google | OIDC | `https://accounts.google.com` | [Google Docs](https://developers.google.com/identity/openid-connect/openid-connect) |
| GitHub | only OAuth2 | `https://github.com` | [GitHub Docs](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps) |
| GitLab | OIDC | `https://gitlab.com` or your instance domain | [GitLab Docs](https://docs.gitlab.com/ee/integration/openid_connect_provider.html) |
| Facebook | OIDC | `https://www.facebook.com` | [Facebook Docs](https://developers.facebook.com/docs/facebook-login/overview) |
| Discord | only OAuth2 | `https://discord.com` | [Discord Docs](https://discord.com/developers/docs/topics/oauth2) |
| Azure | OIDC | `https://login.microsoftonline.com/{tenant}/v2.0`, replace accordingly | [Azure OIDC](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc) |
| Auth0 | OIDC | `https://{yourDomain}.us.auth0.com/`, replace accordingly | [Auth0 OIDC](https://auth0.com/docs/authenticate/protocols/openid-connect-protocol) |
| Keycloak | OIDC | `https://keycloak.example.com/auth/realms/{realm}`, replace accordingly | [Keycloak Docs](https://www.keycloak.org/docs/latest/server_admin/#sso-protocols) |
| Authentik | OIDC | `https://authentik.example.com/application/o/{app}/`, replace accordingly | [Authentik Docs](https://docs.goauthentik.io/docs/providers/oauth2/) |
| Authelia | OIDC | `https://authelia.example.com`, replace accordingly | [Authelia Docs](https://www.authelia.com/integration/openid-connect/introduction/) |

53
docs/content/config/customization.md Normal file
View file

@ -0,0 +1,53 @@
# Customization
HedgeDoc allows you to set a name or logo for your organization.
How this looks and where this is used, can be seen below.
You can also provide a privacy policy, terms of use or an imprint url
for your HedgeDoc instance.
| 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. |
## Example
### Links
![Links on the Frontpage][links-frontpage]
*links for the privacy policy, terms of use and imprint on the front page*
### Logo
For this demo we use this image:
![The demo logo][demo-logo]
![The demo logo on the Frontpage][logo-front-page]
*logo used on the front page*
![The demo logo in the editor (light)][logo-editor-light]
![The demo logo in the editor (dark)][logo-editor-dark]
*logo used in the editor*
### Name
For this demo we use the name `DEMO Corp`
![The name on the Frontpage][name-front-page]
*name used on the front page*
![The name in the editor (light)][name-editor-light]
![The name in the editor (dark)][name-editor-dark]
*name used in the editor*
[links-frontpage]: ../../images/customization/links.png
[demo-logo]: ../../images/customization/demo_logo.png
[logo-front-page]: ../../images/customization/logo/frontpage.png
[logo-editor-light]: ../../images/customization/logo/editor_light.png
[logo-editor-dark]: ../../images/customization/logo/editor_dark.png
[name-front-page]: ../../images/customization/name/frontpage.png
[name-editor-light]: ../../images/customization/name/editor_light.png
[name-editor-dark]: ../../images/customization/name/editor_dark.png

21
docs/content/config/database.md Normal file
View file

@ -0,0 +1,21 @@
# Database
We officially support and test these databases:
- SQLite (for development and smaller instances)
- PostgreSQL
- MariaDB
!!! warning
We don't necessarily support MySQL.
<!-- markdownlint-disable proper-names -->
| environment variable | default | example | description |
|-----------------------|---------|---------------------|----------------------------------------------------------------------------------------|
| `HD_DATABASE_TYPE` | - | `postgres` | The database type you want to use. This can be `postgres`, `mariadb` or `sqlite`. |
| `HD_DATABASE_NAME` | - | `hedgedoc` | The name of the database to use. When using SQLite, this is the path to the database file. |
| `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_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`.* |
<!-- markdownlint-enable proper-names -->

13
docs/content/config/general.md Normal file
View file

@ -0,0 +1,13 @@
# General
| environment variable | default | example | description |
|--------------------------|------------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| `HD_BASE_URL` | - | `https://md.example.com` | The URL the HedgeDoc instance is accessed with, like it is entered in the browser |
| `HD_BACKEND_PORT` | 3000 | | The port the backend process listens on. |
| `HD_FRONTEND_PORT` | 3001 | | The port the frontend process listens on. |
| `HD_RENDERER_BASE_URL` | Content of HD_BASE_URL | | The URL the renderer runs on. If omitted this will be the same as `HD_BASE_URL`. For more detail see [this faq entry][faq-entry] |
| `HD_INTERNAL_API_URL` | Content of HD_BASE_URL | `http://localhost:3000` | This URL is used by the frontend to access the backend directly if it can't reach the backend using the `HD_BASE_URL` |
| `HD_LOGLEVEL` | warn | | The loglevel that should be used. Options are `error`, `warn`, `info`, `debug` or `trace`. |
| `HD_SHOW_LOG_TIMESTAMP` | true | | Specifies if a timestamp should be added to the log statements. Disabling is useful for extern log management (systemd etc.) |
[faq-entry]: ../../faq/index.md#why-should-i-want-to-run-my-renderer-on-a-different-sub-domain

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

@ -0,0 +1,29 @@
# Configuration
HedgeDoc can be configured via environment variables either directly or via an `.env` file.
## The `.env` file
The `.env` file should be in the root directory of the HedgeDoc application and
contains key-value pairs of environment variables and their corresponding value.
In the official Docker container this is `/usr/src/app/.env`
This can for example look like this:
<!-- markdownlint-disable proper-names -->
```ini
HD_BASE_URL="http://localhost:8080"
HD_SESSION_SECRET="change_me_in_production"
HD_DATABASE_TYPE="sqlite"
HD_DATABASE_NAME="./hedgedoc.sqlite"
HD_MEDIA_BACKEND="filesystem"
HD_MEDIA_BACKEND_FILESYSTEM_UPLOAD_PATH="uploads/"
```
<!-- markdownlint-enable proper-names -->
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 for local development,
but it is **not** meant to be used in production without prior changes.

8
docs/content/config/integrations.md Normal file
View file

@ -0,0 +1,8 @@
# Integrations
| 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 |
-->

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

@ -0,0 +1,30 @@
# Azure Blob Storage
You can use [Microsoft Azure Blob Storage][azure] to handle your image uploads in HedgeDoc.
All you need to do is to get the [connection string][connection-string] 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][azure-cli], using your connection string,
with the following command:
<!-- markdownlint-disable line-length -->
```shell
az storage container create --name <NAME> --public-access blob--connection-string "<CONNECTION_STRING>"
```
<!-- markdownlint-enable line-length -->
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:
(with the appropriate substitution for `<CONNECTION_STRING>` and `<NAME>` of course)
```dotenv
HD_MEDIA_BACKEND="azure"
HD_MEDIA_BACKEND_AZURE_CONNECTION_STRING="<CONNECTION_STRING>"
HD_MEDIA_BACKEND_AZURE_CONTAINER="<NAME>"
```
[azure]: https://azure.microsoft.com/services/storage/blobs/
[connection-string]: https://docs.microsoft.com/azure/storage/common/storage-account-keys-manage
[azure-cli]: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli

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

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

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

@ -0,0 +1,31 @@
# Imgur
!!! warning "Imgur saves anonymous images for only 6 month"
Imgur will delete images not associated with any account 6 month after the last access.
This means that if you use imgur as your image backend, you may lose images
uploaded by you or your users. See this [FAQ entry][faq-entry]
You can use [Imgur][imgur] 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:
(with the appropriate substitution for `<IMGUR_CLIENT_ID>` of course)
```dotenv
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][deletion-token]) in the column `backendData`.
[faq-entry]: https://help.imgur.com/hc/en-us/articles/14415587638029-Imgur-Terms-of-Service-Update-April-19-2023
[imgur]: https://imgur.com
[deletion-token]: https://apidocs.imgur.com/#949d6cb0-5e55-45f7-8853-8c44a108399c

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

@ -0,0 +1,35 @@
# S3-compatible
You can use [Amazon S3][s3] or any other S3-compatible storage (like [MinIO][minIO]
or [Ceph Object Gateway][ceph]) 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:
(with the appropriate substitution for `<ACCESS_KEY>`, `<SECRET_KEY>`,
`<BUCKET>`, `<REGION>`, and `<ENDPOINT>` of course)
```dotenv
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>"
HD_MEDIA_BACKEND_S3_REGION="<REGION>"
HD_MEDIA_BACKEND_S3_PATH_STYLE="<true|false>"
```
`<ENDPOINT>` should be an URL and contain the protocol, the domain and if necessary the port.
For example: `https://s3.example.org` or `http://s3.example.org:9000`
`<PATH_STYLE>` should be set to `true` if you are using a S3-compatible storage like MinIO that
uses path-style URLs.
If you use Amazon S3, `<ENDPOINT>` should contain your [Amazon Region][amazon-region].
For example: If your Amazon Region is `us-east-2`,your endpoint `<ENDPOINT>`
should be `https://s3.us-east-2.amazonaws.com`.
[s3]: https://aws.amazon.com/s3/
[minIO]: https://min.io
[ceph]: https://docs.ceph.com/en/latest/radosgw/
[amazon-region]: https://docs.aws.amazon.com/general/latest/gr/s3.html

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

@ -0,0 +1,74 @@
# WebDAV
You can use any [WebDAV][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:
(with the appropriate substitution for `<CONNECTION_STRING>`,
`<UPLOAD_DIR>`, and `<PUBLIC_URL>` of course)
```dotemv
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][nextcloud-folder] that will hold
your uploads (e.g `HedgeDoc`).
3. [Share][nextcloud-share] 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][nextcloud-webdav]. 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:
```dotenv
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.
[webdav]: https://en.wikipedia.org/wiki/WebDAV
[nextcloud-folder]: https://docs.nextcloud.com/server/latest/user_manual/en/files/access_webgui.html#creating-or-uploading-files-and-directories
[nextcloud-share]: https://docs.nextcloud.com/server/latest/user_manual/en/files/sharing.html#public-link-shares
[nextcloud-webdav]: https://docs.nextcloud.com/server/latest/user_manual/en/files/access_webdav.html

11
docs/content/config/notes.md Normal file
View file

@ -0,0 +1,11 @@
# Notes
| environment variable | default | example | description |
|-----------------------------------|---------|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `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. |
| `HD_GUEST_ACCESS` | `write` | `deny`, `read`, `write`, `create` | Defines the maximum access level for guest users to the instance. If guest access is set lower than the "everyone" permission of a note then the note permission will be overridden. |
| `HD_PERMISSION_DEFAULT_LOGGED_IN` | `write` | `none`, `read`, `write` | The default permission for the "logged-in" group that is set on new notes. |
| `HD_PERMISSION_DEFAULT_EVERYONE` | `read` | `none`, `read`, `write` | The default permission for the "everyone" group (logged-in & guest users), that is set on new notes created by logged-in users. Notes created by guests always set this to "write". |
| `HD_PERSIST_INTERVAL` | 10 | `0`, `5`, `10`, `20` | The time interval in **minutes** for the periodic note revision creation during realtime editing. `0` deactivates the periodic note revision creation. |
| `HD_REVISION_RETENTION_DAYS` | 0 | | The number of days a revision should be kept. If the config option is not set or set to 0, all revisions will be kept forever. |