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

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