1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
# Manual Installation
!!! info "Requirements on your server"
- Node.js 10.13 or higher
- 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 Classic](https://classic.yarnpkg.com) 1.22 or higher (Yarn 2 is currently not supported)
- 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 prebuilt frontend, so building it yourself is not necessary.
1. Check if you meet the [requirements at the top of this document](#manual-installation).
2. Download the [latest release](https://hedgedoc.org/latest-release/) and extract it.
<small>Alternatively, you can use Git to clone the repository and checkout a release, e.g. with `git clone -b 1.7.2 https://github.com/hedgedoc/hedgedoc.git`.</small>
3. Enter the directory and execute `bin/setup`, which will install the dependencies and create example configs.
4. Configure HedgeDoc: To get started, you can use this minimal `config.json`:
```json
{
"production": {
"db": {
"dialect": "sqlite",
"storage": "./db.hedgedoc.sqlite"
},
"urlAddPort": true,
"domain": "localhost"
}
}
```
It's also possible to use environment variables.
For details, have a look at [the configuration documentation](../configuration.md).
5. *:octicons-light-bulb-16: If you use the release tarball for 1.7.0 or newer, this step can be skipped.*
Build the frontend bundle by running `yarn run build`.
6. It is recommended to start your server manually once:
```shell
NODE_ENV=production yarn start
```
This way it's easier to see warnings or errors that might occur.
<small>You can leave out `NODE_ENV=production` for development.</small>
7. If you use the example config, HedgeDoc should now be available at [http://127.0.0.1:3000](http://127.0.0.1:3000).
8. Run the server as you like (node, forever, pm2, systemd, Init-Scripts).
See [below](#systemd-unit-example) for an example using systemd.
## Upgrading
!!! warning
Before you upgrade, **always read the release notes**.
You can find them on our [releases page](https://hedgedoc.org/releases/).
If you want to upgrade HedgeDoc from an older version, follow these steps:
1. Check if you still meet the [requirements at the top of this document](#requirements-on-your-server).
2. Ensure you read the [release notes](https://hedgedoc.org/releases/) of all versions between your current version
and the latest release.
2. Fully stop your old HedgeDoc server.
3. [Download](https://hedgedoc.org/latest-release/) the new release and extract it over the old directory.
<small>If you use Git, you can check out the new tag with e.g. `git fetch origin && git checkout 1.7.2`</small>
5. Run `bin/setup`. This will take care of installing dependencies. It is safe to run on an existing installation.
6. *:octicons-light-bulb-16: If you used the release tarball for 1.7.0 or newer, this step can be skipped.*
Build the frontend bundle by running `yarn run build`.
7. It is recommended to start your server manually once:
```shell
NODE_ENV=production yarn start
```
This way it's easier to see warnings or errors that might occur.
8. You can now restart the HedgeDoc server!
## Systemd Unit Example
Using the unit file below, you can run HedgeDoc as a systemd service.
!!! warning
- In this example, you must configure HedgeDoc using the `config.json` file and the
`production` key.
- Make sure the user and group `hedgedoc` exists and has appropriate permissions in the
directory you installed HedgeDoc in or change the `User` and `Group` settings in the unit
file.
- Make sure `WorkingDirectory` points to the directory you installed HedgeDoc in.
- Make sure `ReadWritePaths` contains all directories HedgeDoc might write to. This may
include the `public/uploads` folder if you configured local storage. If you use SQLite, you
must also include the directory where the database file is saved. **Do not save the SQLite
file in the root directory of the HedgeDoc installation**, but create a subfolder like `db`!
- If you use an external database like PostgreSQL or MariaDB, make sure to add a corresponding
`After` statement.
```ini
[Unit]
Description=HedgeDoc - The best platform to write and share markdown.
Documentation=https://docs.hedgedoc.org/
After=network.target
# Uncomment if you use MariaDB/MySQL
# After=mysql.service
# Uncomment if you use PostgreSQL
# After=postgresql.service
[Service]
Type=exec
Environment=NODE_ENV=production
Restart=always
RestartSec=2s
ExecStart=/usr/bin/yarn start --production
CapabilityBoundingSet=
NoNewPrivileges=true
PrivateDevices=true
RemoveIPC=true
LockPersonality=true
ProtectControlGroups=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectKernelLogs=true
ProtectClock=true
ProtectHostname=true
ProtectProc=noaccess
RestrictRealtime=true
RestrictSUIDSGID=true
RestrictNamespaces=true
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
SystemCallArchitectures=native
SystemCallFilter=@system-service
# You may have to adjust these settings
User=hedgedoc
Group=hedgedoc
WorkingDirectory=/opt/hedgedoc
# Example: local storage for uploads and SQLite
# ReadWritePaths=/opt/hedgedoc/public/uploads /opt/hedgedoc/db
[Install]
WantedBy=multi-user.target
```
|
