diff options
Diffstat (limited to 'docs/content/setup')
| -rw-r--r-- | docs/content/setup/cloudron.md | 10 | ||||
| -rw-r--r-- | docs/content/setup/docker-linuxserver.md | 20 | ||||
| -rw-r--r-- | docs/content/setup/docker.md | 20 | ||||
| -rw-r--r-- | docs/content/setup/heroku.md | 6 | ||||
| -rw-r--r-- | docs/content/setup/kubernetes.md | 5 | ||||
| -rw-r--r-- | docs/content/setup/manual-setup.md | 45 | ||||
| -rw-r--r-- | docs/content/setup/reverse-proxy.md | 95 | ||||
| -rw-r--r-- | docs/content/setup/yunohost.md | 8 |
8 files changed, 209 insertions, 0 deletions
diff --git a/docs/content/setup/cloudron.md b/docs/content/setup/cloudron.md new file mode 100644 index 00000000..3085e6bd --- /dev/null +++ b/docs/content/setup/cloudron.md @@ -0,0 +1,10 @@ +# Cloudron + +HedgeDoc is available as a 1-click install on [Cloudron](https://cloudron.io). Cloudron makes it easy to run apps like HedgeDoc on your server and keep them up-to-date and secure. + +[](https://cloudron.io/button.html?app=io.hackmd.cloudronapp) + +The source code for the package can be found [here](https://git.cloudron.io/cloudron/codimd-app). + +There is a [demo instance](https://my.demo.cloudron.io) (username: cloudron password: cloudron) where +you can experiment with running HedgeDoc. diff --git a/docs/content/setup/docker-linuxserver.md b/docs/content/setup/docker-linuxserver.md new file mode 100644 index 00000000..33302f55 --- /dev/null +++ b/docs/content/setup/docker-linuxserver.md @@ -0,0 +1,20 @@ +# LinuxServer.io HedgeDoc Image + +[](https://discord.gg/YWrKVTn "realtime support / chat with the community and the team.") +[](https://github.com/linuxserver/docker-hedgedoc/releases) +[](https://github.com/linuxserver/docker-hedgedoc/packages) +[](https://gitlab.com/linuxserver.io/docker-hedgedoc/container_registry) +[](https://microbadger.com/images/linuxserver/hedgedoc "Get your own version badge on microbadger.com") +[](https://hub.docker.com/r/linuxserver/hedgedoc) +[](https://hub.docker.com/r/linuxserver/hedgedoc) +[](https://ci.linuxserver.io/job/Docker-Pipeline-Builders/job/docker-hedgedoc/job/main/) +[](https://ci-tests.linuxserver.io/linuxserver/hedgedoc/latest/index.html) + +[LinuxServer.io](https://linuxserver.io) have created an Ubuntu-based multi-arch container image for x86-64, arm64 and armhf. + +- It supports all the environment variables detailed in the [configuration documentation](../configuration.md) to modify it according to your needs. +- It gets rebuilt on new releases from HedgeDoc and also weekly if necessary to update any other package changes in the underlying container, making it easy to keep your HedgeDoc instance up to date. +- It also details how to easily [utilize Docker networking to reverse proxy](https://github.com/linuxserver/docker-hedgedoc/#application-setup) HedgeDoc using their [SWAG docker image](https://github.com/linuxserver/docker-swag) + +In order to contribute check the LinuxServer.io [GitHub repository](https://github.com/linuxserver/docker-hedgedoc/) for HedgeDoc. +And to find all tags and versions of the image, check the [Docker Hub repository](https://hub.docker.com/r/linuxserver/hedgedoc). diff --git a/docs/content/setup/docker.md b/docs/content/setup/docker.md new file mode 100644 index 00000000..f6aeb833 --- /dev/null +++ b/docs/content/setup/docker.md @@ -0,0 +1,20 @@ +# HedgeDoc Docker Image + +[](http://play-with-docker.com?stack=https://github.com/hedgedoc/container/raw/master/docker-compose.yml&stack_name=hedgedoc) + +## Debian-based version + +[](https://quay.io/repository/hedgedoc/hedgedoc) + +## Alpine-based version + +[](https://quay.io/repository/hedgedoc/hedgedoc) + +The easiest way to setup HedgeDoc using docker are using the following three commands: + +```sh +git clone https://github.com/hedgedoc/container.git hedgedoc-container +cd hedgedoc-container +docker-compose up +``` +Read more about it in the [container repository](https://github.com/hedgedoc/container). diff --git a/docs/content/setup/heroku.md b/docs/content/setup/heroku.md new file mode 100644 index 00000000..e6280051 --- /dev/null +++ b/docs/content/setup/heroku.md @@ -0,0 +1,6 @@ +# Heroku Deployment + +You can quickly setup a sample Heroku HedgeDoc application by clicking the button +below. + +[](https://heroku.com/deploy?template=https://github.com/hedgedoc/hedgedoc/tree/master) diff --git a/docs/content/setup/kubernetes.md b/docs/content/setup/kubernetes.md new file mode 100644 index 00000000..7ece0d20 --- /dev/null +++ b/docs/content/setup/kubernetes.md @@ -0,0 +1,5 @@ +# 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/manual-setup.md b/docs/content/setup/manual-setup.md new file mode 100644 index 00000000..6cb7c75a --- /dev/null +++ b/docs/content/setup/manual-setup.md @@ -0,0 +1,45 @@ +# Manual Installation + +## Requirements on your server + +- Node.js 10.13 or up +- Database (PostgreSQL, MySQL, MariaDB, SQLite, MSSQL) + The database must use charset `utf8`. This is typically the default in PostgreSQL and SQLite. + In MySQL and MariaDB UTF-8 might need to be set with `alter database <DBNAME> character set utf8 collate utf8_bin;` + Be aware of older MySQL and MariaDB versions which sometimes use shorter representations of UTF-8 than 4 bytes. + This can break if symbols with more bytes are used. + You can use `alter database <DBNAME> character set utf8mb4 COLLATE utf8mb4_unicode_ci` to be on the safe side. +- NPM (and its dependencies, [node-gyp](https://github.com/nodejs/node-gyp#installation)) +- Yarn +- Bash (for the setup script) +- For **building** the HedgeDoc frontend you need a machine with at least **2 GB** RAM. + - Starting with release 1.7 the release tarball includes the frontend, so building it yourself is not necessary. + +## Instructions + +1. Check if you meet the [requirements at the top of this document](#requirements-on-your-server). +2. Download a [release](https://github.com/hedgedoc/hedgedoc/releases) tarball and extract it. + Alternatively, you can use Git to clone the repository and checkout a release, e.g. with `git clone -b 1.7.0 https://github.com/hedgedoc/hedgedoc.git`. +3. Enter the directory and type `bin/setup`, which will install the dependencies and create configs. +4. Modify the file named `config.json` or configure HedgeDoc through environment variables which will overwrite the configs, see docs [here](https://github.com/hedgedoc/hedgedoc/blob/master/docs/configuration.md). +5. **If using the release tarball for 1.7.0 or newer, this step can be skipped.** + Build the frontend bundle by `yarn run build` (use `yarn run dev` if you are in development) +6. Modify the file named `.sequelizerc`, change the value of the variable `url` to your db connection string. For example: + - `postgres://username:password@localhost:5432/hedgedoc` + - `mysql://username:password@localhost:3306/hedgedoc` + - `sqlite:///opt/hedgedoc/hedgedoc.sqlite` (note that you need to use an absolute path to the SQLite file) +7. It is recommended to start your server manually once: `NODE_ENV=production yarn start`, this way it's easier to see warnings or errors that might occur (leave out `NODE_ENV=production` for development). +8. Run the server as you like (node, forever, pm2, SystemD, Init-Scripts) + +## How to upgrade your installation + +If you are upgrading HedgeDoc from an older version, follow these steps: + +1. Check if you meet the [requirements at the top of this document](#requirements-on-your-server). +2. Verify which version you were running before and take a look at [migrations and breaking changes](../guides/migrations-and-breaking-changes.md) to see if additional steps, or configuration changes are necessary! +3. Fully stop your old HedgeDoc server. +4. `git pull` or unzip a new release in the directory. +5. Run `bin/setup`. This will take care of installing dependencies. It is safe to run on an existing installation. +6. Build front-end bundle by `yarn run build` (use `yarn run dev` if you are in development). +7. It is recommended to start your server manually once: `NODE_ENV=production yarn start`, this way it's easier to see warnings or errors that might occur (leave out `NODE_ENV=production` for development). +8. You can now restart the HedgeDoc server! diff --git a/docs/content/setup/reverse-proxy.md b/docs/content/setup/reverse-proxy.md new file mode 100644 index 00000000..b1e7f32f --- /dev/null +++ b/docs/content/setup/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: +``` +<VirtualHost *:443> + 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 +</VirtualHost> +``` + diff --git a/docs/content/setup/yunohost.md b/docs/content/setup/yunohost.md new file mode 100644 index 00000000..dac4c0b1 --- /dev/null +++ b/docs/content/setup/yunohost.md @@ -0,0 +1,8 @@ +YunoHost +=== + +HedgeDoc is available as a 1-click install on [YunoHost](https://yunohost.org/). YunoHost is a Debian GNU/Linux based distribution packaged with free software that automates the installation of a personal web server. + +[](https://install-app.yunohost.org/?app=hedgedoc) + +The source code for the package can be found [here](https://github.com/YunoHost-Apps/hedgedoc_ynh). |