From 520d0933cbd5b5d2b47bad53ab7f127d6149df35 Mon Sep 17 00:00:00 2001 From: David Mehren Date: Fri, 24 Mar 2023 17:46:47 +0100 Subject: [PATCH] docs: add getting started guide Signed-off-by: David Mehren --- docs/content/setup/getting_started.md | 35 +++++++++++++++++++++++++++ docs/mkdocs.yml | 4 ++- 2 files changed, 38 insertions(+), 1 deletion(-) create mode 100644 docs/content/setup/getting_started.md diff --git a/docs/content/setup/getting_started.md b/docs/content/setup/getting_started.md new file mode 100644 index 000000000..4fee5fd4f --- /dev/null +++ b/docs/content/setup/getting_started.md @@ -0,0 +1,35 @@ +HedgeDoc 2 currently supports deployment using [Docker Compose](https://docs.docker.com/compose/install/). + +The `docker` folder in the root of our repo contains all files required to get started, deploying +HedgeDoc 2, a PostgreSQL database and a Caddy reverse proxy. + +## Development or local testing + +To run HedgeDoc 2 locally, you do not need to change anything. +Caddy will automatically generate a TLS certificate for `hedgedoc2.localhost` using its internal CA. +After running `docker compose up`, visit [https://hedgedoc2.localhost](https://hedgedoc2.localhost). +You will have to accept the TLS warning in your browser the first time the page is opened. + +## Production setup + +!!! danger "HedgeDoc 2 is not yet production ready!" + This section explains how a production deployment of HedgeDoc 2 on a publicly accessible domain + might look in the future. + HedgeDoc 2 itself is not production ready yet, so only use these instructions to set up an + instance for testing with your friends. + +For a production setup, first set a unique session secret with +`sed -i "s/session_secret/$(pwgen -s 64)/" .env`. + +Then open the `.env` file and edit `HD_BASE_URL`. It needs to contain the full URL of your instance, +like it will be entered in the browser. If you enter a URL starting with `https://`, Caddy will +automatically gather certificates via *Let's Encrypt* (or its internal CA in case of `.localhost` domains). +Make sure your host is accessible under the domain from `HD_BASE_URL`, otherwise Let's Encrypt +validation will fail. + +Optionally, you can also change + +- `HD_MEDIA_BACKEND`: If you do not want HedgeDoc to handle media uploads itself, configure another backend + here. For more information, [see the media backend docs](/config/#media). +- `HD_AUTH_*`: If you do not want to use the integrated auth system, + you can [consult the authentication docs](/config/#authentication) for details. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index ab9b78b63..b7e961486 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: HedgeDoc +site_name: HedgeDoc 2 site_url: https://docs.hedgedoc.org repo_url: https://github.com/hedgedoc/hedgedoc site_description: 'HedgeDoc Documentation' @@ -7,6 +7,8 @@ docs_dir: content edit_uri: https://github.com/hedgedoc/hedgedoc/edit/master/docs/content/ nav: - Home: index.md + - Installation: + - Getting Started: setup/getting_started.md - Configuration: - Configuration: config/index.md - Media: