summaryrefslogtreecommitdiff
path: root/docs/content/setup
diff options
context:
space:
mode:
Diffstat (limited to 'docs/content/setup')
-rw-r--r--docs/content/setup/docker.md95
-rw-r--r--docs/content/setup/getting-started.md25
-rw-r--r--docs/content/setup/manual-setup.md174
3 files changed, 245 insertions, 49 deletions
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 41426514..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="http://social.codimd.org/" target="_blank" rel="noreferer noopener">:fontawesome-brands-mastodon:{: .mastodon }Mastodon</a> or <a href="http://social.codimd.org/twitter" target="_blank" rel="noreferer noopener">:fontawesome-brands-twitter:{: .twitter }Twitter</a> for updates.
+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..acc739ca 100644
--- a/docs/content/setup/manual-setup.md
+++ b/docs/content/setup/manual-setup.md
@@ -1,41 +1,141 @@
# 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. Modify the file named `.sequelizerc`, change the value of the variable `url` to your db connection string. For example:
+ - `postgres://username:password@localhost:5432/hedgedoc`
+ - `mysql://username:password@localhost:3306/hedgedoc`
+ - `sqlite:///opt/hedgedoc/hedgedoc.sqlite` (note that you need to use an absolute path to the SQLite file)
+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.
+ <small>You can leave out `NODE_ENV=production` for development.</small>
+8. If you use the example config, HedgeDoc should now be available at [http://127.0.0.1:3000](http://127.0.0.1:3000).
+9. 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
+```