github/hedgedoc
1
0
Fork 0
mirror of https://github.com/hedgedoc/hedgedoc.git synced 2025-04-19 16:16:13 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #984 from hedgedoc/docs/upgrade-instructions

Browse source
This commit is contained in:
Yannick Bungers 2021-04-17 16:33:49 +02:00 • committed by GitHub
commit 58f5282ccb
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 237 additions and 100 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
docs/content/guides/migrations-and-breaking-changes.md
View file

@ -1,55 +0,0 @@
# Migrations and Notable Changes
## Migrating to 1.4.0
We dropped support for node 6 with this version. If you have any trouble running this version, please double check that you are running at least node 8!
## Migrating to 1.3.2
This is not a breaking change, but to stay up to date with the community
repository, you may need to update a few urls. This is not a breaking change.
See more at [issue #10](https://github.com/hedgedoc/hedgedoc/issues/10)
### Native setup using git
Change the upstream remote using `git remote set-url origin https://github.com/hedgedoc/hedgedoc.git`.
### Docker
When you use our [container repository](https://github.com/hedgedoc/container)
(which was previously `hedgedoc-container`) all you can simply run `git pull` and
your `docker-compose.yml` will be updated.
When you setup things yourself, make sure you use the new image:
[`quay.io/hedgedoc/hedgedoc`](https://quay.io/repository/hedgedoc/hedgedoc?tab=tags).
### Heroku
All you need to do is [disconnect GitHub](https://devcenter.heroku.com/articles/github-integration#disconnecting-from-github)
and [reconnect it](https://devcenter.heroku.com/articles/github-integration#enabling-github-integration)
with this new repository.
Or you can use our Heroku button and redeploy your instance and link the old
database again.
## Migrating to 1.1.0
We deprecated the older lower case config style and moved on to camel case style. Please have a look at the current `config.json.example` and check the warnings on startup.
*Notice: This is not a breaking change right now but will be in the future*
## Migrating to 0.5.0
[migration-to-0.5.0 migration tool](https://github.com/hackmdio/migration-to-0.5.0)
We don't use LZString to compress socket.io data and DB data after version 0.5.0.
Please run the migration tool if you're upgrading from the old version.
## Migrating to 0.4.0
[migration-to-0.4.0 migration tool](https://github.com/hackmdio/migration-to-0.4.0)
We've dropped MongoDB after version 0.4.0.
So here is the migration tool for you to transfer the old DB data to the new DB.
This tool is also used for official service.

97
docs/content/setup/docker.md
View file

@ -1,20 +1,93 @@
# HedgeDoc Docker Image
[![Try in PWD](https://cdn.rawgit.com/play-with-docker/stacks/cff22438/assets/images/button.png)](http://play-with-docker.com?stack=https://github.com/hedgedoc/container/raw/master/docker-compose.yml&stack_name=hedgedoc)
!!! info "Requirements on your server"
- [Git](https://git-scm.com/)
- [Docker](https://docs.docker.com/get-docker/) 17.03.1 or higher
- [Docker Compose](https://docs.docker.com/compose/install/)
## Debian-based version
The official docker images are [available on quay.io](https://quay.io/repository/hedgedoc/hedgedoc).
We currently only support the `amd64` architecture.
[![Docker Repository on Quay](https://quay.io/repository/hedgedoc/hedgedoc/status "Docker Repository on Quay")](https://quay.io/repository/hedgedoc/hedgedoc)
## Alpine-based version
The easiest way to get started with HedgeDoc and Docker is to use the following `docker-compose.yml`:
[![Docker Repository on Quay](https://quay.io/repository/hedgedoc/hedgedoc/status "Docker Repository on Quay")](https://quay.io/repository/hedgedoc/hedgedoc)
!!! warning
This is a minimal example to get started quickly and not intended for production use.
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
```yaml
version: '3'
services:
database:
image: postgres:9.6-alpine
environment:
- POSTGRES_USER=hedgedoc
- POSTGRES_PASSWORD=password
- POSTGRES_DB=hedgedoc
volumes:
- database:/var/lib/postgresql/data
restart: always
app:
# Make sure to use the latest release from https://hedgedoc.org/latest-release
image: quay.io/hedgedoc/hedgedoc:1.7.2
environment:
- CMD_DB_URL=postgres://hedgedoc:password@database:5432/hedgedoc
- CMD_DOMAIN=localhost
- CMD_URL_ADDPORT=true
volumes:
- uploads:/hedgedoc/public/uploads
ports:
- "3000:3000"
restart: always
depends_on:
- database
volumes:
database:
uploads:
```
After executing `docker-compose up`, HedgeDoc should be available at [http://127.0.0.1:3000](http://127.0.0.1:3000).
You can now continue to configure your container with environment variables.
Check out [the configuration docs](/configuration) for more details.
## Upgrading
!!! warning
Before you upgrade, **always read the release notes**.
You can find them on our [releases page](https://hedgedoc.org/releases/).
!!! info "Upgrading to 1.7"
Together with changing the name to "HedgeDoc" the default username,
password and database name have been changed in `docker-compose.yml`.
In order to migrate the existing database to the new default credentials, run
```shell
docker-compose exec database createuser --superuser -Uhackmd postgres
docker-compose exec database psql -Upostgres -c "alter role hackmd rename to hedgedoc; alter role hedgedoc with password 'password'; alter database hackmd rename to hedgedoc;"
```
before running `docker-compose up`.
You can upgrade to the latest release by stopping the containers and changing the referenced image version in `docker-compose.yml`.
Then run `docker-compose up` to start HedgeDoc again.
### Migrating from CodiMD & HackMD
If you currently use CodiMD or HackMD, you should be able to swap the docker image for ours.
See [the general migration hints](/setup/getting-started/#migrating-from-codimd-hackmd) for compatibility details.
## Backup
If you use a PostgreSQL database, you can leverage this command to create a backup:
```shell
docker-compose exec database pg_dump hedgedoc -U hedgedoc > backup.sql
```
## Restore
If you want to restore your PostgreSQL backup, run these commands before starting the application for the first time:
```shell
docker-compose up -d database
cat backup.sql | docker exec -i $(docker-compose ps -q database) psql -U hedgedoc
```
Read more about it in the [container repository](https://github.com/hedgedoc/container).

23
docs/content/setup/getting-started.md
View file

@ -6,5 +6,28 @@ To set up your instance follow these steps:
1. Choose an installation method and follow the instructions
2. [Configure your reverse proxy](https://docs.hedgedoc.org/guides/reverse-proxy/)
3. [Configure HedgeDoc](https://docs.hedgedoc.org/configuration/)
4. If you didn't disable [local accounts](/configuration/#email-local-account), you can use the "Sign In" button to
create an account, login and start using HedgeDoc.
Follow us on <a href="https://social.hedgedoc.org/" target="_blank" rel="noreferer noopener">:fontawesome-brands-mastodon:{: .mastodon }Mastodon</a> or <a href="https://social.hedgedoc.org/twitter" target="_blank" rel="noreferer noopener">:fontawesome-brands-twitter:{: .twitter }Twitter</a> for updates.
## Upgrading HedgeDoc
HedgeDoc follows [Semantic Versioning](https://semver.org/).
This means that minor and patch releases should not introduce user-facing backwards-incompatible changes.
You can find more details about upgrading in the instructions of your installation method.
!!! warning
Before you upgrade, **always read the release notes**.
You can find them on our [releases page](https://hedgedoc.org/releases/).
## Migrating from CodiMD & HackMD
Migrating from CodiMD <= 1.6.0 or HackMD <= 1.1.0 to HedgeDoc should be safe,
just make sure to read the release notes.
A particular issue that has come up is when handling TLS connections using a reverse proxy.
You must [set the `X-Forwarded-Proto` header correctly](https://docs.hedgedoc.org/guides/reverse-proxy/#reverse-proxy-config).
Migrating from more recent versions of CodiMD is not guaranteed to work, although some community members
[reported success migrating from CodiMD 2.2](https://community.hedgedoc.org/t/solved-upgrade-from-dockerlized-codimd/271).
If you successfully migrated from other versions, please report your upgrade results in the [community forum](https://community.hedgedoc.org/).

160
docs/content/setup/manual-setup.md
View file

@ -1,41 +1,137 @@
# Manual Installation
## Requirements on your server
!!! 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.
- 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.
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.
## Instructions
## Upgrading
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.2 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](../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. 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).
7. Run the server as you like (node, forever, pm2, SystemD, Init-Scripts)
!!! warning
Before you upgrade, **always read the release notes**.
You can find them on our [releases page](https://hedgedoc.org/releases/).
## How to upgrade your installation
If you want to upgrade HedgeDoc from an older version, follow these steps:
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.
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. 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).
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
```

2
docs/mkdocs.yml
View file

@ -36,7 +36,6 @@ nav:
- MinIO: guides/minio-image-upload.md
- S3: guides/s3-image-upload.md
- Migrate from Etherpad: guides/migrate-etherpad.md
- Breaking Changes: guides/migrations-and-breaking-changes.md
- Migration Troubleshooting: guides/migration-troubleshooting.md
- Terms of Use Setup: guides/providing-terms.md
- Configuration: configuration.md
@ -60,6 +59,7 @@ markdown_extensions:
emoji_generator: !!python/name:materialx.emoji.to_svg
- attr_list
- footnotes
- admonition
theme:
name: 'material'
language: en