summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorYannick Bungers2021-04-17 16:33:49 +0200
committerGitHub2021-04-17 16:33:49 +0200
commit58f5282ccb0cd32970e4e2646c11e3c22ac72772 (patch)
tree344db932d46c450704c5af54ddd0a697edda3d6b /docs
parent08e73d00701f768a4c99dcf67f72371910a8fe28 (diff)
parente8465aa8beac309edb36a3d4d2fc85317c921b48 (diff)
Merge pull request #984 from hedgedoc/docs/upgrade-instructions
Diffstat (limited to '')
-rw-r--r--docs/content/guides/migrations-and-breaking-changes.md55
-rw-r--r--docs/content/setup/docker.md95
-rw-r--r--docs/content/setup/getting-started.md23
-rw-r--r--docs/content/setup/manual-setup.md170
-rw-r--r--docs/mkdocs.yml2
5 files changed, 241 insertions, 104 deletions
diff --git a/docs/content/guides/migrations-and-breaking-changes.md b/docs/content/guides/migrations-and-breaking-changes.md
deleted file mode 100644
index bbc320b1..00000000
--- a/docs/content/guides/migrations-and-breaking-changes.md
+++ /dev/null
@@ -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.
diff --git a/docs/content/setup/docker.md b/docs/content/setup/docker.md
index f6aeb833..11ff9b02 100644
--- a/docs/content/setup/docker.md
+++ b/docs/content/setup/docker.md
@@ -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:
+```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:
-```sh
-git clone https://github.com/hedgedoc/container.git hedgedoc-container
-cd hedgedoc-container
-docker-compose up
+```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).
diff --git a/docs/content/setup/getting-started.md b/docs/content/setup/getting-started.md
index a8180793..2b1f8653 100644
--- a/docs/content/setup/getting-started.md
+++ b/docs/content/setup/getting-started.md
@@ -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/).
diff --git a/docs/content/setup/manual-setup.md b/docs/content/setup/manual-setup.md
index 4d03b752..e32d6843 100644
--- a/docs/content/setup/manual-setup.md
+++ b/docs/content/setup/manual-setup.md
@@ -1,41 +1,137 @@
# 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.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)
-
-## 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.
+!!! 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. 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
+```
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 5b04cc40..5a5056ef 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -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