Logo

https://d33wubrfki0l68.cloudfront.net/a8c2537ed889d70488435691b04807e0ee3b93b0/5ab40/_images/hedgedoc.svg

HedgeDoc

#lang-nodejs #web #collaborative-editing 

HedgeDoc (formerly CodiMD / HackMD) is an open-source software written in Node.js. HedgeDoc lets you create real-time collaborative markdown notes. It is inspired by Hackpad, Etherpad and similar collaborative editors.

HedgeDoc is licensed under the AGPLv3.

Note

For this guide you should be familiar with the basic concepts of

Prerequisites

We’re using Node.js version 14.

[isabell@stardust ~]$ uberspace tools version use node 14
Selected Node.js version 14
The new configuration is adapted immediately. Minor updates will be applied automatically.
[isabell@stardust ~]$

Setup your Domain:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

You’ll need your MySQL credentials. Get them with my_print_defaults:

[isabell@stardust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
[isabell@stardust ~]$

Installation

Download

Check whether the marked line is the latest release.

[isabell@stardust ~]$ VERSION=1.7.1
[isabell@stardust ~]$ wget https://github.com/hedgedoc/hedgedoc/releases/download/$VERSION/hedgedoc-$VERSION.tar.gz
[...]
100%[======================================================>] 50,784,713  16.8MB/s   in 2.9s
[isabell@stardust ~]$ tar --extract --gzip --file=hedgedoc-$VERSION.tar.gz
[isabell@stardust ~]$ rm --verbose hedgedoc-$VERSION.tar.gz
removed hedgedoc-x.x.x.tar.gz
[isabell@stardust ~]$

Setup

Then install the dependencies. This step may take a few minutes.

[isabell@stardust ~]$ cd hedgedoc
[isabell@stardust hedgedoc]$ bin/setup
Copying config files...
Installing packages...
yarn install v1.22.5
[1/5] Validating package.json...
[2/5] Resolving packages...
[3/5] Fetching packages...
info There appears to be trouble with your network connection. Retrying...
info fsevents@1.2.13: The platform "linux" is incompatible with this module.
info "fsevents@1.2.13" is an optional dependency and failed compatibility check. Excluding it from installation.
info fsevents@2.1.3: The platform "linux" is incompatible with this module.
info "fsevents@2.1.3" is an optional dependency and failed compatibility check. Excluding it from installation.
[4/5] Linking dependencies...
[5/5] Building fresh packages...
Done in 253.95s.
yarn install v1.22.5
[1/5] Validating package.json...
[2/5] Resolving packages...
success Already up-to-date.
Done in 1.15s.


Edit the following config file to setup HedgeDoc server and client.
Read more info at https://github.com/hedgedoc/hedgedoc#configuration-files

* config.json           -- HedgeDoc config
* .sequelizerc          -- db config
[isabell@stardust hedgedoc]$

Database

Create a Database.

[isabell@stardust hedgedoc]$ mysql --verbose --execute="CREATE DATABASE ${USER}_hedgedoc"
--------------
CREATE DATABASE isabell_hedgedoc
--------------

[isabell@stardust hedgedoc]$

Configuration

First we remove the config file that was generated by the setup because it might be very confusing. It was a copy of config.json.example if you like to have a look at it.

[isabell@stardust hedgedoc]$ rm --verbose config.json
removed ‘config.json’
[isabell@stardust hedgedoc]$

Note

You can set here some options in json format you can’t yet set with environment variables. For other configuration options, check the configuration documentation.

Create ~/hedgedoc/config.json with the following content:

{}

Edit the file ~/hedgedoc/.sequelizerc with the following content and adjust the highlighted line.:

var path = require('path');

module.exports = {
    'config':          path.resolve('config.json'),
    'migrations-path': path.resolve('lib', 'migrations'),
    'models-path':     path.resolve('lib', 'models'),
    'url':             'mysql://isabell:YourMySQL-Password@localhost:3306/isabell_hedgedoc'
}

Note

You will also need the highlighted string later at the step for the ~/etc/services.d/hedgedoc.ini, so note it.

Generate session secret

The cookie session secret is used to sign the session cookie. If none is set, one will randomly be generated on each startup, meaning all your users will be logged out.
You will need the highlighted string at the next step for the ~/etc/services.d/hedgedoc.ini.
[isabell@stardust ~]$ pwgen 32 1
somethingSuperRandom
[isabell@stardust ~]$

Setup daemon

Note

You can set a lot of environment variables. For other configuration options, check the configuration documentation. The prefix for the variables may change in a future release because of the renaming of the project.

Create ~/etc/services.d/hedgedoc.ini with the following content:

[program:hedgedoc]
environment=
  NODE_ENV="production",
  CMD_ALLOW_EMAIL_REGISTER="false",
  CMD_ALLOW_ANONYMOUS="false",
  CMD_ALLOW_FREEURL="true",
  CMD_SESSION_SECRET="somethingSuperRandom",
  CMD_DB_URL="mysql://isabell:YourMySQL-Password@localhost:3306/isabell_hedgedoc"
directory=%(ENV_HOME)s/hedgedoc
command=yarn start
startsecs=60
autostart=yes
autorestart=yes

After creating the configuration, tell supervisord to refresh its configuration and start the service:

[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE                            RUNNING   pid 26020, uptime 0:03:14
[isabell@stardust ~]$

If it’s not in state RUNNING after one minute (at first you will see STARTING), check your configuration. You can also check the run log with supervisorctl tail -f hedgedoc. You can ignore the warnings about the domain, port and ssl settings.

Configure web server

Note

HedgeDoc is running on port 3000 in the default configuration.

To make the application accessible from the outside, configure a web backend:

[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$

Create a User

Even if you have deactivated the web based user registration you can always create users with the following command. The username has to be in the form of an email address. You will then be asked to choose a password.

[isabell@stardust hedgedoc]$ NODE_ENV=production bin/manage_users --add isabell@uber.space
Password for isabell@uber.space:*************
Created user with email isabell@uber.space
[isabell@stardust hedgedoc]$

You should now be able to access your HedgeDoc via https://isabell.uber.space

Updates

Note

Check the release notes regularly or subscribe to the project’s GitHub release feed with your favorite feed reader to stay informed about new updates and releases.

While HedgeDoc 2.0 is currently under development and 1.7 as latest release is also having bigger changes you should watch HedgeDocs manual installation guide to notice if instructions have been changed. You should also read the release notes. Make sure you always download the already build tarball as the building process needs at least 2 GB RAM, so building is not possible on uberspace.

Manual update

Check whether the marked line is the latest release or the version you like to update to.

[isabell@stardust ~]$ supervisorctl stop hedgedoc
hedgedoc: stopped
[isabell@stardust ~]$ mv --verbose hedgedoc hedgedoc_old
‘hedgedoc’ -> ‘hedgedoc_old’
[isabell@stardust ~]$ VERSION=1.7.1
[isabell@stardust ~]$ wget https://github.com/hedgedoc/hedgedoc/releases/download/$VERSION/hedgedoc-$VERSION.tar.gz
[...]
100%[======================================================>] 50,784,713  16.8MB/s   in 2.9s
[isabell@stardust ~]$ tar --extract --gzip --file=hedgedoc-$VERSION.tar.gz
[isabell@stardust ~]$ rm --verbose hedgedoc-$VERSION.tar.gz
removed ‘hedgedoc-x.x.x.tar.gz’
[isabell@stardust ~]$ cp --verbose hedgedoc_old/config.json hedgedoc/config.json
‘hedgedoc_old/config.json’ -> ‘hedgedoc/config.json’
[isabell@stardust ~]$ cp --verbose hedgedoc_old/.sequelizerc hedgedoc/.sequelizerc
‘hedgedoc_old/.sequelizerc’ -> ‘hedgedoc/.sequelizerc’
[isabell@stardust ~]$ cd hedgedoc
[isabell@stardust hedgedoc]$ bin/setup
Copying config files...
Installing packages...
yarn install v1.22.5
[1/5] Validating package.json...
[2/5] Resolving packages...
[3/5] Fetching packages...
info fsevents@1.2.13: The platform "linux" is incompatible with this module.
info "fsevents@1.2.13" is an optional dependency and failed compatibility check. Excluding it from installation.
info fsevents@2.1.3: The platform "linux" is incompatible with this module.
info "fsevents@2.1.3" is an optional dependency and failed compatibility check. Excluding it from installation.
[4/5] Linking dependencies...
[5/5] Building fresh packages...
Done in 597.69s.
yarn install v1.22.5
[1/5] Validating package.json...
[2/5] Resolving packages...
success Already up-to-date.
Done in 1.22s.

Edit the following config file to setup HedgeDoc server and client.
Read more info at https://github.com/hedgedoc/hedgedoc#configuration-files

* config.json           -- HedgeDoc config
* .sequelizerc          -- db config
[isabell@stardust hedgedoc]$ supervisorctl start hedgedoc
hedgedoc: started
[isabell@stardust hedgedoc]$ supervisorctl tail -f hedgedoc
==> Press Ctrl-C to exit <==
[...] no errors (red colored) should appear
[isabell@stardust hedgedoc]$ cd
[isabell@stardust ~]$ rm --recursive hedgedoc_old
[isabell@stardust ~]$

Under usual circumstances you don’t need to change the config files. The setup script does not override your config files even if it says Copying config files....

Update script

Create ~/bin/hedgedoc-update with the following content:

#!/usr/bin/env bash
ORG=hedgedoc # Organisation or GitHub user
REPO=hedgedoc
LOCAL=$(jq --raw-output .version ~/hedgedoc/package.json)
LATEST=$(curl -s https://api.github.com/repos/$ORG/$REPO/releases/latest | jq --raw-output .tag_name)

function do_upgrade() {
  supervisorctl stop hedgedoc
  mv --verbose ~/hedgedoc ~/hedgedoc_$LOCAL
  VERSION=$LATEST
  cd
  wget https://github.com/hedgedoc/hedgedoc/releases/download/$VERSION/hedgedoc-$VERSION.tar.gz
  tar --extract --gzip --file=hedgedoc-$VERSION.tar.gz
  rm --verbose hedgedoc-$VERSION.tar.gz
  cp --verbose hedgedoc_$LOCAL/config.json hedgedoc/config.json
  cp --verbose hedgedoc_$LOCAL/.sequelizerc hedgedoc/.sequelizerc
  cd hedgedoc
  bin/setup
  supervisorctl start hedgedoc
  echo "You may need to wait a minute until you can access the HedgeDoc web interface"
  echo "If everything works fine you can delete ~/hedgedoc_$LOCAL"
  #rm --recursive ~/hedgedoc_$LOCAL
}

if [ "$LOCAL" = "$LATEST" ]; then
  echo "Your HedgeDoc is already up to date."
else
  if [[ "$LOCAL" < "$LATEST" ]]; then
    echo "There is a new Version available of HedgeDoc"
    echo "The latest Version is $LATEST"
    echo "Your local Version is $LOCAL"
    echo "Upgrades to next major releases are not tested."
    echo "Please read the release notes."
    echo "Also check if the upgrade instructions have changed."
    echo "Your instance might break."
    while true; do
      read -p "Do you wish to proceed with the upgrade? (Y/n) " ANSWER
      if [ "$ANSWER" = "" ]; then
        ANSWER='Y'
      fi
      case $ANSWER in
        [Yy]* | [Jj]* )
          do_upgrade
          break;;
        [Nn]* ) exit;;
        * ) echo "Please answer yes or no. ";;
      esac
    done
  fi
fi

To make this script executable you have to run this once:

[isabell@stardust ~]$ chmod u+x --verbose ~/bin/hedgedoc-update
mode of ‘/home/isabell/bin/hedgedoc-update’ changed from 0664 (rw-rw-r--) to 0764 (rwxrw-r--)
[isabell@stardust ~]$

You can run this script with:

[isabell@stardust ~]$ hedgedoc-update
Your HedgeDoc is already up to date.
[isabell@stardust ~]$

Tested with HedgeDoc 1.7.1, Uberspace 7.8.1.0

Written by: stunkymonkey <http://stunkymonkey.de>, Matthias Kolja Miehl <https://makomi.net>, Kevin Jost <https://github.com/systemsemaphore>, EV21 <uberlab@ev21.de>