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

docs: restructure documentation

Browse source 
This rewrite follows the principles of https://diataxis.fr/

Co-authored-by: Erik Michelson <github@erik.michelson.eu>
Signed-off-by: Philip Molares <philip.molares@udo.edu>
Signed-off-by: Erik Michelson <github@erik.michelson.eu>
This commit is contained in:
Philip Molares 2023-07-02 22:31:04 +02:00 • committed by Tilman Vatteroth
parent e0dd24ed29
commit e07cd62596
68 changed files with 1163 additions and 315 deletions
Download patch file Download diff file Expand all files Collapse all files

5
docs/content/how-to/auth.md Normal file
View file

@ -0,0 +1,5 @@
# How to use other authentication methods
TODO: This pages is still missing some content.
See this issue for more information and if you want to contribute:
<https://github.com/hedgedoc/hedgedoc/issues/4830>

5
docs/content/how-to/backup.md Normal file
View file

@ -0,0 +1,5 @@
# How to back up HedgeDoc
TODO: This pages is still missing some content.
See this issue for more information and if you want to contribute:
<https://github.com/hedgedoc/hedgedoc/issues/4830>

5
docs/content/how-to/database.md Normal file
View file

@ -0,0 +1,5 @@
# Database
TODO: This pages is still missing some content.
See this issue for more information and if you want to contribute:
<https://github.com/hedgedoc/hedgedoc/issues/4830>

42
docs/content/how-to/develop/auth/ldap.md Normal file
View file

@ -0,0 +1,42 @@
# LDAP
If you are developing HedgeDoc and need to test something with an LDAP server you can use the
[`test-openldap`][docker-image] Docker image from [rroemhild][rroemhild].
Simply run
<!-- markdownlint-disable proper-names -->
```shell
docker run --rm -p 10389:10389 -p 10636:10636 rroemhild/test-openldap
```
<!-- markdownlint-enable proper-names -->
and add the following to the `.env` file then start the backend.
```dotenv
HD_AUTH_LDAP_SERVERS="FUTURAMA"
HD_AUTH_LDAP_FUTURAMA_PROVIDER_NAME="Futurama LDAP"
HD_AUTH_LDAP_FUTURAMA_URL="ldap://localhost:10389"
HD_AUTH_LDAP_FUTURAMA_SEARCH_BASE="ou=people,dc=planetexpress,dc=com"
HD_AUTH_LDAP_FUTURAMA_SEARCH_FILTER=(&(uid={{username}})(objectClass=inetOrgPerson))
HD_AUTH_LDAP_FUTURAMA_DISPLAY_NAME_FIELD="uid"
HD_AUTH_LDAP_FUTURAMA_USERID_FIELD="uid"
HD_AUTH_LDAP_FUTURAMA_BIND_DN="cn=admin,dc=planetexpress,dc=com"
HD_AUTH_LDAP_FUTURAMA_BIND_CREDENTIALS="GoodNewsEveryone"
```
You should be able to log in with either of these logins (`username` : `password`):
- `professor` : `professor`
- `fry` : `fry`
- `zoidberg` : `zoidberg`
- `hermes` : `hermes`
- `leela` : `leela`
- `bender` : `bender`
- `amy` : `amy`
If you need to know more about which information are held by each of these accounts, have a look at
the [documentation](https://github.com/rroemhild/docker-test-openldap#ldap-structure).
[docker-image]: https://github.com/rroemhild/docker-test-openldap
[rroemhild]: https://github.com/rroemhild

22
docs/content/how-to/develop/docker.md Normal file
View file

@ -0,0 +1,22 @@
# Building Docker images
To build Docker images of the backend or frontend use the following commands.
Make sure that you have installed the [Docker BuildKit Plugin][buildkit] and
execute the commands from the root level of the project.
Otherwise, the build process may fail.
<!-- markdownlint-disable proper-names -->
```shell
docker buildx build -f backend/docker/Dockerfile -t hedgedoc-backend .
```
<!-- markdownlint-enable proper-names -->
or
<!-- markdownlint-disable proper-names -->
```shell
docker buildx build -f frontend/docker/Dockerfile -t hedgedoc-frontend .
```
<!-- markdownlint-enable proper-names -->
[buildkit]: https://docs.docker.com/build/install-buildx/

44
docs/content/how-to/develop/documentation.md Normal file
View file

@ -0,0 +1,44 @@
# Documentation
Our documentation is build with [mkdocs][mkdocs]. While you can write documentation with every text
editor you like, if you want to build the documentation and want to see at how it will look you need
to have [python3][python3] and [mkdocs][mkdocs] installed.
## Writing
<!-- markdownlint-disable proper-names -->
All documentation files are found in the `docs/content` directory of
the [hedgedoc/hedgedoc repo](https://github.com/hedgedoc/hedgedoc). These files are just normal
markdown files with nothing special about them.
<!-- markdownlint-enable proper-names -->
The configuration for mkdocs lies in the `docs` folder in a file called `mkdocs.yml`. With that file
the theme and menu - among others - can be configured.
**Please note:** Any new files need to be linked to by other files or put in the navigation,
otherwise the files will be very hard to find on the documentation website.
## Building
To build the documentation locally you need to perform the following steps:
1. Make sure you have [python3][python3] installed. `python3 --version`
2. Go into the `docs` folder.
3. Install all the dependencies (E.g. with a [venv](https://docs.python.org/3/library/venv.html))
with `pip install -r requirements.txt`
4. Start the mkdocs dev server (`mkdocs serve`) or build the documentation (`mkdocs build`).
If you run `mkdcs serve` a local server will serve the mkdocs files and change the served files as
you write documentation.
## Deployment
The documentation is deployed with [mkdocs][mkdocs].
<!-- markdownlint-disable proper-names -->
The repository [docs.hedgedoc.org][docs.hedgedoc.org] is used to deploy the actual website
to github.io. Currently only the `master` branch is deployed as it contains the latest release.
<!-- markdownlint-enable proper-names -->
[mkdocs]: https://www.mkdocs.org
[python3]: https://www.python.org/
[docs.hedgedoc.org]: https://github.com/hedgedoc/docs.hedgedoc.org

65
docs/content/how-to/develop/frontend.md Normal file
View file

@ -0,0 +1,65 @@
# Frontend
## Environment Variables
The following environment variables are recognized by the frontend process.
| Name | Possible Values | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HD_BASE_URL | Any URL with protocol, domain and optionally directory and port. Must end with a trailing slash. (e.g. `http://localhost:3001/`) | The URL under which the frontend is expected. Setting this is mandatory so the server side rendering can generate assets URLs. You only need to set this yourself if you use the production mode. |
| HD_RENDERER_BASE_URL | Same as `HD_BASE_URL` | You can provide this variable if the renderer should use another domain than the editor. This is recommended for security reasons but not mandatory. This variable is optional and will fallback to `HD_BASE_URL` |
| NEXT_PUBLIC_USE_MOCK_API | `true`, `false` | Will activate the mocked backend |
| NEXT_PUBLIC_TEST_MODE | `true`, `false` | Will activate additional HTML attributes that are used to identify elements for test suits. |
Variables that start with `NEXT_PUBLIC_` will be compiled into the build. You can't change them
after compilation. You shouldn't need to set them yourself. Use the designated npm tasks instead.
## UI Test
Curious about the new look and feel? We provide a demo of the new UI on
[HedgeDoc.dev][hedgedoc-dev]. This version uses mocked data and has no data persistence.
The UI test is hosted by [netlify][netlify]. Please check their [privacy policy][netlify-privacy]
as well as [ours][privacy].
## Running Tests
### Unit
Unit testing is done via jest.
1. Run `yarn test`
### End2End
We use [cypress][cypress] for e2e tests.
1. Start the frontend with `yarn start:dev:test` (or use a test build using `yarn build:test`
which you can start using `yarn start`). The usage of `:test` is mandatory!
2. Run `yarn cy:open` to open the cypress test loader
3. Choose your browser and start a test suite
To run all tests in a headless browser use `yarn cy:run:chrome` or `yarn cy:run:firefox`
### Bundle analysis
You can inspect the generated production-bundle files to look for optimization issues.
1. run `yarn analyze`. This will overwrite any existing builds!
2. Open the generated `.next/server/analyze/server.html` in your favourite browser
## Enable Debug Logging in Production
The debug logger can be enabled in production by setting `debugLogging` in the browser's
local storage to `true`. This can be done e.g. by executing this JavaScript command
in the browser's console.
```javascript
window.localStorage.setItem("debugLogging", "true");
```
[hedgedoc-dev]: https://hedgedoc.dev
[netlify]: https://netlify.com
[netlify-privacy]: https://netlify.com/privacy
[privacy]: https://hedgedoc.org/privacy-policy
[cypress]: https://cypress.io

162
docs/content/how-to/develop/setup.md Normal file
View file

@ -0,0 +1,162 @@
# Development Setup
To run HedgeDoc 2.0 you need three components: the backend, the frontend and the reverse proxy.
Backend and Frontend are included in the [HedgeDoc repo][hedgedoc-repo].
The reverse proxy can be chosen by preference. For development, we recommend caddy
and the provided configuration.
## Quick guide for development setup
This describes the easiest way to start a local development environment. For other deployments
follow the description below.
To run HedgeDoc 2.0 you need three components: the backend, the frontend and the reverse proxy.
Backend and Frontend are included in the [HegdeDoc repo][hedgedoc-repo].
The reverse proxy can be chosen by preference. For development, we recommend caddy
and the provided configuration.
1. Clone [our repository][hedgedoc-repo] and go into its directory
<!-- markdownlint-disable proper-names -->
```shell
git clone https://github.com/hedgedoc/hedgedoc.git
cd hedgedoc
```
<!-- markdownlint-enable proper-names -->
2. Install Node.js. You need at least Node 16, but we recommend Node 20.
3. Install [Yarn][yarn]
4. Install Caddy (select one of the two options)
- [Download][caddy] and place the `caddy` binary in `dev-reverse-proxy`.
Ensure it is executable with `chmod +x caddy`. Users of macOS may need to run
`xattr -d com.apple.quarantine ./caddy` to lift the quarantine for executables
from the internet.
- Install Caddy using your package manager
5. Install the dependencies in repo root directory with `yarn install`
6. Create the `.env` config file by copying the example: `cp .env.example .env`
7. Run `yarn start:dev`
> This will execute the backend, frontend and reverse proxy at once
8. Use your browser to go to <http://localhost:8080>. This may take a while because everything is
compiled on the fly.
## More detailed development setup
The following sections describe a more detailed setup of all components.
## Preconditions
If you want to run HedgeDoc in dev mode some preconditions have to be met.
1. Make sure that Node.js is installed. You need at least Node 16, but we recommend Node 18.
2. Make sure that [Yarn][yarn] is installed.
<!-- markdownlint-disable proper-names -->
3. Clone this repo (e.g. `git clone https://github.com/hedgedoc/hedgedoc.git hedgedoc`)
<!-- markdownlint-enable proper-names -->
4. Go into the cloned directory
## Installing the dependencies
Because we use Yarn workspaces, Yarn collects the dependencies of all packages automatically in one
central top-level `node_modules` folder.
To install the dependencies execute `yarn install` at the top level of the cloned repository.
Execute this command ONLY there. There is no need to execute the install-command for every package.
It's important to use [Yarn][yarn]. We don't support `npm` or any other package
manager and using anything else than Yarn won't work.
## Create the configuration
HedgeDoc 2 is configured using environment variables.
For development, we recommend creating an `.env` file.
1. Create an `.env` file. We recommend to use the example file by running `cp .env.example .env`
You can modify this file according to the [configuration documentation][config-docs].
2. Make sure that you've set `HD_SESSION_SECRET` in your `.env` file. Otherwise, the backend
won't start.
> In dev mode you don't need a secure secret. So use any value. If you want to generate a secure
> session secret you can use
> e.g. `openssl rand -hex 16 | sed -E 's/(.*)/HD_SESSION_SECRET=\1/' >> .env`.
3. Make sure that `HD_BASE_URL` in `.env` is set to the base url where HedgeDoc should be available.
In local dev environment this is most likely `http://localhost:8080`.
## Build the `commons` package
Some code is shared by backend and frontend. This code lives in the `commons` package and needs
to be built so frontend and backend can import it.
This only needs to be done once, except if you've changed code in the commons package.
1. Go into the `commons` directory.
2. Execute `yarn build` to build the commons package.
## Setting up the Backend
**Note:** The backend can be mocked instead of starting it for real. This is useful,
if you just want to work on the frontend. See the "Mocked backend" section below.
1. Go into the `backend` directory.
2. Start the backend by running `yarn start:dev` for dev mode or `yarn start` for production.
## Setting up the frontend
The frontend can be run in four different ways. The development mode compiles everything on demand.
So the first time you open a page in the browser it may take some time.
[See here][frontend-setup] for a more detailed description of the environment variables
for the frontend. A special configuration isn't necessary but keep in mind that you execute
all commands from within the `frontend` directory.
### Mocked backend
This task will run the frontend in mock-mode, meaning instead of running a real backend, the
frontend mocks the backend. This way you can work on frontend functionality without starting up the
full development environment. The downside of this method is that you can't save notes and that
realtime collaboration features are not available. To start the development mode,
run `yarn start:dev:mock`. The app should run now and be available under
<http://localhost:3001> in your browser.
### With local backend
To start the development mode with an actual HedgeDoc backend use `yarn start:dev` instead.
This task will automatically set `HD_BASE_URL` to `http://localhost:8080`.
### Production mode
Use `yarn build` to build the app in production mode and save it into the `.next` folder.
The production build is minimized and optimized for best performance. Don't edit the generated
files in the `.next` folder in any way!
You can run the production build using the built-in server with `yarn start`.
You MUST provide the environment variable `HD_BASE_URL` with protocol, domain and (if needed)
subdirectory path (e.g. `http://localhost:3001/`) so the app knows under which URL the frontend
is available in the browser.
If you use the production build then make sure that you set the environment variable `HD_BASE_URL`
to the same value as `HD_BASE_URL` in the backend.
### Production mock build
It is also possible to create a production build that uses the emulated backend by using
`yarn build:mock`. This is usually not needed except for demonstration purposes like
`https://hedgedoc.dev`.
## Running backend and frontend together
To use backend and frontend together in development mode you'll need a local reverse proxy that
combines both services under one URL origin.
We recommend to use our pre-configured [Caddy][caddy] configuration.
### Running the reverse proxy
1. Download the latest version of Caddy from [the Caddy website][caddy] or alternatively install
it using your package manager. You don't need any plugin. Place the downloaded binary in
the directory `dev-reverse-proxy`. Don't forget to mark the file as executable using
`chmod +x caddy`. Users of macOS may need to run `xattr -d com.apple.quarantine ./caddy`
to lift the quarantine for executables from the internet.
2. Start Caddy using `./caddy run` (if you downloaded the binary manually) or `caddy run`
(if you installed Caddy via a package manager).
3. Open your browser on <http://localhost:8080>
[hedgedoc-repo]: https://github.com/hedgedoc/hedgedoc
[yarn]: https://yarnpkg.com/getting-started/install
[caddy]: https://caddyserver.com/
[config-docs]: /references/config/
[frontend-setup]: ./frontend.md

34
docs/content/how-to/index.md Normal file
View file

@ -0,0 +1,34 @@
# How-to guides
How-to guides target the more advanced users and guide them
through a variety of topics, addressing non-trivial use-cases.
They are more advanced than tutorials and assume some knowledge of HedgeDoc.
<!-- markdownlint-disable no-inline-html -->
<div class='topic-container'>
<a href='/how-to/reverse-proxy/'>
<div class='topic'>
<span>↩️️</span>
<span>Configure a reverse proxy</span>
</div>
</a>
<a href='/how-to/backup/'>
<div class='topic'>
<span>💾</span>
<span>Back up your instance</span>
</div>
</a>
<a href='/how-to/auth/'>
<div class='topic'>
<span>🔑</span>
<span>Customize authentication</span>
</div>
</a>
<a href='/how-to/database/'>
<div class='topic'>
<span>🗄</span>
<span>Use another database</span>
</div>
</a>
</div>
<!-- markdownlint-enable no-inline-html -->

217
docs/content/how-to/reverse-proxy.md Normal file
View file

@ -0,0 +1,217 @@
# How to use a reverse proxy
<!-- markdownlint-disable proper-names -->
When having multiple webservers or other applications running, that also use
port 80 and 443, you probably want to use a reverse proxy to serve HedgeDoc.
We'll assume the domain you use for the instance is <https://md.example.com>, so please
substitute your actual domain anywhere you encounter <https://md.example.com>.
## Configuring the reverse proxy
We have collected some example configurations for popular reverse proxies below.
At the end is also a list of generic things the reverse proxy must do, if you prefer
to write your own config or use a reverse proxy not mentioned here.
### Traefik
As [traefik][traefik] has direct access to your running Docker containers, there is no need to
configure extra ports. Instead, you'll only have to add the following labels to the services
in your `docker-compose.yml`:
<!-- markdownlint-disable line-length no-space-in-code -->
??? abstract "docker-compose.yml"
```yaml
backend:
image: ghcr.io/hedgedoc/hedgedoc/backend:2.0-alpha
volumes:
- $PWD/.env:/usr/src/app/backend/.env
- hedgedoc_uploads:/usr/src/app/backend/uploads
labels:
traefik.enable: "true"
traefik.http.routers.hedgedoc_2_backend.rule: "Host(`md.example.com`) && PathPrefix(`/realtime`, `/api`, `/public`)"
traefik.http.routers.hedgedoc_2_backend.tls: "true"
traefik.http.routers.hedgedoc_2_backend.tls.certresolver: "letsencrypt"
traefik.http.services.hedgedoc_2_backend.loadbalancer.server.port: "3000"
traefik.http.services.hedgedoc_2_backend.loadbalancer.server.scheme: "http"
frontend:
image: ghcr.io/hedgedoc/hedgedoc/frontend:2.0-alpha
environment:
HD_BASE_URL: "${HD_BASE_URL}"
labels:
traefik.enable: "true"
traefik.http.routers.hedgedoc_2_frontend.rule: "Host(`md.example.com`)"
traefik.http.routers.hedgedoc_2_frontend.tls: "true"
traefik.http.routers.hedgedoc_2_frontend.tls.certresolver: "letsencrypt"
traefik.http.services.hedgedoc_2_frontend.loadbalancer.server.port: "3001"
traefik.http.services.hedgedoc_2_frontend.loadbalancer.server.scheme: "http"
```
<!-- markdownlint-enable line-length no-space-in-code -->
We added [Let's Encrypt][letsencrypt] as a certificate resolver, as it enables you to
quickly use HTTPS. If you don't want to use that feel free to change
the `.certresolver` variables accordingly.
If you used the `docker-compose.yml` file from the tutorial, please remove
the service `proxy` and the volume `caddy_data` as caddy is no longer needed when using traefik.
### Other reverse proxies
In the following we'll also assume that you run a HedgeDoc backend on port `3000`,
a HedgeDoc frontend on port `3001`.
Furthermore, we assume that you have TLS certificates located at
`/etc/letsencrypt/live/md.example.com/fullchain.pem`
and
`/etc/letsencrypt/live/md.example.com/privkey.pem` respectively
and are using [Let's Encrypt][letsencrypt] for your certificates.
Replace these paths with the actual paths to your certificates.
**Preparations when using the default docker-compose.yml:**
If your starting with the `docker-compose.yml` file from the tutorial,
you need to add the `ports` entry for both `backend` and `frontend` as following.
<!-- markdownlint-disable no-space-in-code -->
??? abstract "docker-compose.yml"
```yaml
backend:
image: ghcr.io/hedgedoc/hedgedoc/backend:2.0-alpha
volumes:
- $PWD/.env:/usr/src/app/backend/.env
- hedgedoc_uploads:/usr/src/app/backend/uploads
ports:
- "3000:3000"
frontend:
image: ghcr.io/hedgedoc/hedgedoc/frontend:2.0-alpha
environment:
HD_BASE_URL: "${HD_BASE_URL}"
ports:
- "3001:3001"
```
<!-- markdownlint-enable no-space-in-code -->
Also, you want to remove the service `proxy` and the volume `caddy_data`
to avoid port conflicts with your reverse-proxy software.
#### nginx
Here is an example configuration for [nginx][nginx].
<!-- markdownlint-disable code-block-style -->
??? abstract "nginx config"
```
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
server_name md.example.com;
location ~ ^/(api|public|uploads|apidoc)/ {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location /realtime {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
location / {
proxy_pass http://127.0.0.1:3001;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
listen [::]:443 ssl http2;
listen 443 ssl http2;
ssl_certificate fullchain.pem;
ssl_certificate_key privkey.pem;
include options-ssl-nginx.conf;
ssl_dhparam ssl-dhparams.pem;
}
```
<!-- markdownlint-disable code-block-style -->
#### Apache
You will need these modules enabled: `proxy`, `proxy_http` and `proxy_wstunnel`.
Here is an example config snippet for [Apache][apache]:
<!-- markdownlint-disable code-block-style -->
??? abstract "Apache config"
```
<VirtualHost *:443>
ServerName md.example.com
RewriteEngine on
RewriteCond %{REQUEST_URI} ^/realtime [NC]
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://127.0.0.1:3000/$1 [P,L]
ProxyPass /api http://127.0.0.1:3000/
ProxyPass /apidoc http://127.0.0.1:3000/
ProxyPass /public http://127.0.0.1:3000/
ProxyPass /realtime http://127.0.0.1:3000/
ProxyPassReverse /api http://127.0.0.1:3000/
ProxyPassReverse /apidoc http://127.0.0.1:3000/
ProxyPassReverse /public http://127.0.0.1:3000/
ProxyPassReverse /realtime http://127.0.0.1:3000/
ProxyPass / http://127.0.0.1:3001/
ProxyPassReverse / http://127.0.0.1:3001/
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
SSLCertificateFile /etc/letsencrypt/live/md.example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/md.example.com/privkey.pem
Include /etc/letsencrypt/options-ssl-apache.conf
</VirtualHost>
```
<!-- markdownlint-enable code-block-style -->
#### Generic
Here is a list of things your reverse proxy needs to do to let HedgeDoc work:
- Websocket `Upgrade` requests at path `/realtime`.
- Passing `/realtime` to <http://localhost:3000>
- Passing `/api/*` to <http://localhost:3000>
- Passing `/public/*` to <http://localhost:3000>
- Passing `/uploads/*` to <http://localhost:3000>
- Passing `/apidoc/*` to <http://localhost:3000>
- Passing `/*` to <http://localhost:3001>
- Set the `X-Forwarded-Proto` header
In essence there are a few special urls that need to be handled by the HedgeDoc backend
and everything else is handled by the frontend.
<!-- markdownlint-enable proper-names -->
[traefik]: https://traefik.io/traefik/
[letsencrypt]: https://letsencrypt.org/
[nginx]: https://nginx.org/
[apache]: https://httpd.apache.org/