From dc76d158e7a20b1ced0cdde2c5cc83c83ff9d7b9 Mon Sep 17 00:00:00 2001 From: Tilman Vatteroth Date: Tue, 2 Feb 2021 19:35:10 +0100 Subject: [Docs] Extend setup page with community methods Signed-off-by: Tilman Vatteroth --- docs/content/guides/reverse-proxy.md | 95 +++++++++++++++++++++++++++++++++++ docs/content/setup/arch-linux.md | 5 ++ docs/content/setup/index.md | 8 --- docs/content/setup/kubernetes-helm.md | 7 +++ docs/content/setup/kubernetes.md | 5 -- docs/content/setup/reverse-proxy.md | 95 ----------------------------------- docs/mkdocs.yml | 18 ++++--- 7 files changed, 118 insertions(+), 115 deletions(-) create mode 100644 docs/content/guides/reverse-proxy.md create mode 100644 docs/content/setup/arch-linux.md delete mode 100644 docs/content/setup/index.md create mode 100644 docs/content/setup/kubernetes-helm.md delete mode 100644 docs/content/setup/kubernetes.md delete mode 100644 docs/content/setup/reverse-proxy.md (limited to 'docs') diff --git a/docs/content/guides/reverse-proxy.md b/docs/content/guides/reverse-proxy.md new file mode 100644 index 00000000..b1e7f32f --- /dev/null +++ b/docs/content/guides/reverse-proxy.md @@ -0,0 +1,95 @@ +# Using a Reverse Proxy with HedgeDoc + +If you want to use a reverse proxy to serve HedgeDoc, here are the essential +configs that you'll have to do. + +This documentation will cover HTTPS setup, with comments for HTTP setup. + +## HedgeDoc config + +[Full explanation of the configuration options](../configuration.md) + +| `config.json` parameter | Environment variable | Value | Example | +|-------------------------|----------------------|-------|---------| +| `domain` | `CMD_DOMAIN` | The full domain where your instance will be available | `hedgedoc.example.com` | +| `host` | `CMD_HOST` | An ip or domain name that is only available to HedgeDoc and your reverse proxy | `localhost` | +| `port` | `CMD_PORT` | An available port number on that IP | `3000` | +| `path` | `CMD_PATH` | path to UNIX domain socket to listen on (if specified, `host` or `CMD_HOST` and `port` or `CMD_PORT` are ignored) | `/var/run/hedgedoc.sock` | +| `protocolUseSSL` | `CMD_PROTOCOL_USESSL` | `true` if you want to serve your instance over SSL (HTTPS), `false` if you want to use plain HTTP | `true` | +| `useSSL` | | `false`, the communications between HedgeDoc and the proxy are unencrypted | `false` | +| `urlAddPort` | `CMD_URL_ADDPORT` | `false`, HedgeDoc should not append its port to the URLs it links | `false` | +| `hsts.enable` | `CMD_HSTS_ENABLE` | `true` if you host over SSL, `false` otherwise | `true` | + + +## Reverse Proxy config + +### Generic + +The reverse proxy must allow websocket `Upgrade` requests at path `/sockets.io/`. + +It must pass through the scheme used by the client (http or https). + +### Nginx + +Here is an example configuration for Nginx. + +``` +map $http_upgrade $connection_upgrade { + default upgrade; + '' close; +} +server { + server_name hedgedoc.example.com; + + location / { + 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 /socket.io/ { + 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; + } + + 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; +} +``` +### Apache +You will need these modules enabled: `proxy`, `proxy_http` and `proxy_wstunnel`. +Here is an example config snippet: +``` + + ServerName hedgedoc.example.com + + RewriteEngine on + RewriteCond %{REQUEST_URI} ^/socket.io [NC] + RewriteCond %{HTTP:Upgrade} =websocket [NC] + RewriteRule /(.*) ws://127.0.0.1:3000/$1 [P,L] + + ProxyPass / http://127.0.0.1:3000/ + ProxyPassReverse / http://127.0.0.1:3000/ + + 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/hedgedoc.example.com/fullchain.pem + SSLCertificateKeyFile /etc/letsencrypt/live/hedgedoc.example.com/privkey.pem + Include /etc/letsencrypt/options-ssl-apache.conf + +``` + diff --git a/docs/content/setup/arch-linux.md b/docs/content/setup/arch-linux.md new file mode 100644 index 00000000..1ffcabf2 --- /dev/null +++ b/docs/content/setup/arch-linux.md @@ -0,0 +1,5 @@ +# Arch Linux + +HedgeDoc is available in the Arch Linux _community_ repository. + +[Link to the package](https://archlinux.org/packages/community/any/hedgedoc/) diff --git a/docs/content/setup/index.md b/docs/content/setup/index.md deleted file mode 100644 index 253450b7..00000000 --- a/docs/content/setup/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# Installation / Upgrading -You can run HedgeDoc in a number of ways: - -- [Docker](docker) -- [Cloudron](cloudron) -- [LinuxServer.io (multi-arch docker)](docker-linuxserver) -- [Heroku](heroku) -- [Manual setup](manual-setup) diff --git a/docs/content/setup/kubernetes-helm.md b/docs/content/setup/kubernetes-helm.md new file mode 100644 index 00000000..67a27e82 --- /dev/null +++ b/docs/content/setup/kubernetes-helm.md @@ -0,0 +1,7 @@ +# Helm Chart + +You can deploy HedgeDoc on your Kubernetes cluster using `helm`. + +[HedgeDoc Helm Chart by nicholaswilde on Artifact Hub](https://artifacthub.io/packages/helm/nicholaswilde/hedgedoc) + +[Source Code](https://nicholaswilde.github.io/helm-charts/) diff --git a/docs/content/setup/kubernetes.md b/docs/content/setup/kubernetes.md deleted file mode 100644 index 7ece0d20..00000000 --- a/docs/content/setup/kubernetes.md +++ /dev/null @@ -1,5 +0,0 @@ -# Kubernetes - -HedgeDoc currently does not support any deployment via Kubernetes. - -If you want to help us creating a helm chart, then feel free to contact us on [Matrix](https://chat.hedgedoc.org/) or [Discourse](https://community.hedgedoc.org/). diff --git a/docs/content/setup/reverse-proxy.md b/docs/content/setup/reverse-proxy.md deleted file mode 100644 index b1e7f32f..00000000 --- a/docs/content/setup/reverse-proxy.md +++ /dev/null @@ -1,95 +0,0 @@ -# Using a Reverse Proxy with HedgeDoc - -If you want to use a reverse proxy to serve HedgeDoc, here are the essential -configs that you'll have to do. - -This documentation will cover HTTPS setup, with comments for HTTP setup. - -## HedgeDoc config - -[Full explanation of the configuration options](../configuration.md) - -| `config.json` parameter | Environment variable | Value | Example | -|-------------------------|----------------------|-------|---------| -| `domain` | `CMD_DOMAIN` | The full domain where your instance will be available | `hedgedoc.example.com` | -| `host` | `CMD_HOST` | An ip or domain name that is only available to HedgeDoc and your reverse proxy | `localhost` | -| `port` | `CMD_PORT` | An available port number on that IP | `3000` | -| `path` | `CMD_PATH` | path to UNIX domain socket to listen on (if specified, `host` or `CMD_HOST` and `port` or `CMD_PORT` are ignored) | `/var/run/hedgedoc.sock` | -| `protocolUseSSL` | `CMD_PROTOCOL_USESSL` | `true` if you want to serve your instance over SSL (HTTPS), `false` if you want to use plain HTTP | `true` | -| `useSSL` | | `false`, the communications between HedgeDoc and the proxy are unencrypted | `false` | -| `urlAddPort` | `CMD_URL_ADDPORT` | `false`, HedgeDoc should not append its port to the URLs it links | `false` | -| `hsts.enable` | `CMD_HSTS_ENABLE` | `true` if you host over SSL, `false` otherwise | `true` | - - -## Reverse Proxy config - -### Generic - -The reverse proxy must allow websocket `Upgrade` requests at path `/sockets.io/`. - -It must pass through the scheme used by the client (http or https). - -### Nginx - -Here is an example configuration for Nginx. - -``` -map $http_upgrade $connection_upgrade { - default upgrade; - '' close; -} -server { - server_name hedgedoc.example.com; - - location / { - 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 /socket.io/ { - 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; - } - - 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; -} -``` -### Apache -You will need these modules enabled: `proxy`, `proxy_http` and `proxy_wstunnel`. -Here is an example config snippet: -``` - - ServerName hedgedoc.example.com - - RewriteEngine on - RewriteCond %{REQUEST_URI} ^/socket.io [NC] - RewriteCond %{HTTP:Upgrade} =websocket [NC] - RewriteRule /(.*) ws://127.0.0.1:3000/$1 [P,L] - - ProxyPass / http://127.0.0.1:3000/ - ProxyPassReverse / http://127.0.0.1:3000/ - - 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/hedgedoc.example.com/fullchain.pem - SSLCertificateKeyFile /etc/letsencrypt/live/hedgedoc.example.com/privkey.pem - Include /etc/letsencrypt/options-ssl-apache.conf - -``` - diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index dcdd531a..6179bd68 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -8,14 +8,18 @@ edit_uri: https://github.com/hedgedoc/hedgedoc/edit/master/docs/content/ nav: - Home: index.md - Installation: - - 'Manual Installation': setup/manual-setup.md - - 'Reverse Proxy': setup/reverse-proxy.md - - Docker: setup/docker.md - - Cloudron: setup/cloudron.md - - Heroku: setup/heroku.md - - LinuxServer: setup/docker-linuxserver.md - - Yunohost: setup/yunohost.md + - Official installation methods: + - 'Docker Image': setup/docker.md + - 'Manual Installation': setup/manual-setup.md + - Heroku: setup/heroku.md + - Community installation methods: + - 'LinuxServer Docker Image': setup/docker-linuxserver.md + - 'Helm Chart': setup/kubernetes-helm.md + - 'YunoHost App': setup/yunohost.md + - 'Cloudron App': setup/cloudron.md + - 'Arch Linux Package': setup/arch-linux.md - Guides: + - 'Reverse Proxy': guides/reverse-proxy.md - Authentication: - LDAP: guides/auth/ldap-ad.md - OAuth: guides/auth/oauth.md -- cgit v1.2.3