From 038c1b48689e1e852074f1929eb2e009ed865f74 Mon Sep 17 00:00:00 2001 From: David Mehren Date: Thu, 12 Aug 2021 22:22:39 +0200 Subject: [PATCH 1/8] Port over the FAQ page from hedgedoc.org Signed-off-by: David Mehren --- docs/content/faq.md | 36 ++++++++++++++++++++++++++++++++++++ docs/mkdocs.yml | 2 +- 2 files changed, 37 insertions(+), 1 deletion(-) create mode 100644 docs/content/faq.md diff --git a/docs/content/faq.md b/docs/content/faq.md new file mode 100644 index 000000000..5736f7f03 --- /dev/null +++ b/docs/content/faq.md @@ -0,0 +1,36 @@ +This page collects Frequently Asked Questions of the community. +If you have any questions that aren't answered here, feel free to ask us on [Matrix][matrix.org-url] or stop by our [community forums][hedgedoc-community]. + +[matrix.org-url]: https://chat.hedgedoc.org +[hedgedoc-community]: https://community.hedgedoc.org + +## Why is CodiMD now called HedgeDoc? +The short version: There were two CodiMD-projects on GitHub, the community-driven fork and the original project maintained by the HackMD-team. +To solve this naming conflict, our community-driven version was renamed to HedgeDoc. +For a full writeup, check out the [history overview](https://hedgedoc.org/history/). + + +## Can I run multiple instances on the same database? +No. The HedgeDoc server process is not entirely stateless and therefore running more than one instance will result in missing/broken content for users. +In order to solve issues like HA-capabilities, please use a high level orchestrator that makes sure that always 1 instance is running on your infrastructure and that the database is available. +The server process usually starts within seconds and therefore the possible downtime should be minimal. + + +## Why was the PDF Export feature removed? +We used a headless Chromium instance to generate the PDFs, but that led to some security vulnerabilities and was therefore deactivated. +There are currently plans to re-add this feature in a safe way, but this will most likely take some time and can be expected at the earliest with HedgeDoc 2.1 (but could also take longer). +In the meantime you can use your browsers print to PDF Feature. +This [page](https://www.digitaltrends.com/computing/how-to-save-a-webpage-as-a-pdf/) explains how to do that for multiple browsers. + + +## Why can't I embed some PDFs? +Many servers don't allow the embedding of their content on arbitrary sites. + +For a more technical explanation: +The `X-Frame-Options` header can be used to specify if a given webpage can be embedded. +For security reasons this header is often set to `SAMEORIGIN`, which disallows embedding on other origins. +To be able to embed a PDF inside a HedgeDoc note, the server that hosts the PDF must either send no `X-Frame-Options` +header (which might be insecure) or include the URI of your HedgeDoc instance in an `ALLOW-FROM` statement. +See [Mozillas docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) for more details. +Also note that the `X-Frame-Options` header [is being obsoleted](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors) +by the `frame-ancestors` statement in the `Content-Security-Policy` header. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 46cea7b51..cdd5322b1 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -48,7 +48,7 @@ nav: - 'Operational Transformation': dev/ot.md - Webpack: dev/webpack.md - 'Documentation': dev/documentation.md - - FAQ: https://hedgedoc.org/faq + - FAQ: faq.md markdown_extensions: - toc: permalink: true From c9388add9df7c4dd17fc22a1de96b75197f06d77 Mon Sep 17 00:00:00 2001 From: David Mehren Date: Thu, 12 Aug 2021 22:35:21 +0200 Subject: [PATCH 2/8] Add FAQ entry about iframing HedgeDoc Signed-off-by: David Mehren --- docs/content/faq.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/content/faq.md b/docs/content/faq.md index 5736f7f03..5c0c0aacf 100644 --- a/docs/content/faq.md +++ b/docs/content/faq.md @@ -34,3 +34,14 @@ header (which might be insecure) or include the URI of your HedgeDoc instance in See [Mozillas docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) for more details. Also note that the `X-Frame-Options` header [is being obsoleted](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors) by the `frame-ancestors` statement in the `Content-Security-Policy` header. + +## Why can I not embed a HedgeDoc note in other pages using iframes? +Allowing your HedgeDoc instance to be embedded in other pages increases the risk of [clickjacking](https://en.wikipedia.org/wiki/Clickjacking), +[XSS](https://en.wikipedia.org/wiki/Cross-site_scripting) and other attacks. +Therefore, **we recommend to not enable** this option. +If you still want to allow embedding via iframe, ensure that: + +- Your HedgeDoc instance is served via HTTPS +- `cookiePolicy` / `CMD_COOKIE_POLICY` is set to `none` (Otherwise you will get a `AUTH failed: No cookie transmitted` error.) +- `csp.allowFraming` / `CMD_CSP_ALLOW_FRAMING` is set to `true` + From 6d0187bead5e6fc633b4b53975a248cae04bdfbd Mon Sep 17 00:00:00 2001 From: David Mehren Date: Thu, 12 Aug 2021 22:47:26 +0200 Subject: [PATCH 3/8] Add FAQ entry about broken image upload Signed-off-by: David Mehren --- docs/content/faq.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/content/faq.md b/docs/content/faq.md index 5c0c0aacf..8a5b91b9f 100644 --- a/docs/content/faq.md +++ b/docs/content/faq.md @@ -45,3 +45,9 @@ If you still want to allow embedding via iframe, ensure that: - `cookiePolicy` / `CMD_COOKIE_POLICY` is set to `none` (Otherwise you will get a `AUTH failed: No cookie transmitted` error.) - `csp.allowFraming` / `CMD_CSP_ALLOW_FRAMING` is set to `true` +## I can't upload images or the upload gets stuck +This problem is typically accompanied by the error `Invalid URL: /uploads/` in the log and is often caused by a missing +`domain` / `CMD_DOMAIN` config option or an incorrect reverse proxy config. +Have a look at our [reverse proxy documentation](https://docs.hedgedoc.org/guides/reverse-proxy/) +and make sure that `protocolUseSSL` / `CMD_PROTOCOL_USESSL` is set to `true` if you serve HedgeDoc via HTTPS. + From eb270fdb6b36e06f89070b3f4923dabc30995191 Mon Sep 17 00:00:00 2001 From: David Mehren Date: Thu, 12 Aug 2021 22:58:02 +0200 Subject: [PATCH 4/8] Add FAQ entry about broken migrations Signed-off-by: David Mehren --- docs/content/faq.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/content/faq.md b/docs/content/faq.md index 8a5b91b9f..937550681 100644 --- a/docs/content/faq.md +++ b/docs/content/faq.md @@ -51,3 +51,6 @@ This problem is typically accompanied by the error `Invalid URL: /uploads/` in t Have a look at our [reverse proxy documentation](https://docs.hedgedoc.org/guides/reverse-proxy/) and make sure that `protocolUseSSL` / `CMD_PROTOCOL_USESSL` is set to `true` if you serve HedgeDoc via HTTPS. +## HedgeDoc fails executing migrations and does not start +Unfortunately, older versions of HedgeDoc had some bugs regarding migrations and didn't always record that a migration was executed. +Have a look at the *[Troubleshooting Migrations](/guides/migration-troubleshooting/)* guide for more information. From ccced2d92c3f2df815dd245af52a7a4050e42a6c Mon Sep 17 00:00:00 2001 From: David Mehren Date: Fri, 13 Aug 2021 16:30:45 +0200 Subject: [PATCH 5/8] Change homepage link to new FAQs Signed-off-by: David Mehren --- docs/content/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/index.md b/docs/content/index.md index 3a109a4ff..20efeae50 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -15,6 +15,6 @@ If you have any questions that aren't answered here, feel free to ask us on [Mat [hedgedoc-demo]: https://demo.hedgedoc.org [hedgedoc-history]: https://hedgedoc.org/history -[hedgedoc-faq]: https://hedgedoc.org/faq +[hedgedoc-faq]: /faq [matrix.org-url]: https://chat.hedgedoc.org [hedgedoc-community]: https://community.hedgedoc.org From c1976425da5b925964d9e60bbc3b5dfcf3ce11c8 Mon Sep 17 00:00:00 2001 From: David Mehren Date: Sat, 14 Aug 2021 10:57:29 +0200 Subject: [PATCH 6/8] Use consistent spelling in FAQs Signed-off-by: David Mehren --- docs/content/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/faq.md b/docs/content/faq.md index 937550681..126d8a875 100644 --- a/docs/content/faq.md +++ b/docs/content/faq.md @@ -35,7 +35,7 @@ See [Mozillas docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X- Also note that the `X-Frame-Options` header [is being obsoleted](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors) by the `frame-ancestors` statement in the `Content-Security-Policy` header. -## Why can I not embed a HedgeDoc note in other pages using iframes? +## Why can't I embed a HedgeDoc note in other pages using iframes? Allowing your HedgeDoc instance to be embedded in other pages increases the risk of [clickjacking](https://en.wikipedia.org/wiki/Clickjacking), [XSS](https://en.wikipedia.org/wiki/Cross-site_scripting) and other attacks. Therefore, **we recommend to not enable** this option. From daf7d61ea2dc86ce6f36e1f2441edc8ec2f1fe81 Mon Sep 17 00:00:00 2001 From: David Mehren Date: Sat, 14 Aug 2021 11:04:12 +0200 Subject: [PATCH 7/8] Link to config docs in embedding FAQ Signed-off-by: David Mehren --- docs/content/faq.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/content/faq.md b/docs/content/faq.md index 126d8a875..c21f0a09d 100644 --- a/docs/content/faq.md +++ b/docs/content/faq.md @@ -45,6 +45,8 @@ If you still want to allow embedding via iframe, ensure that: - `cookiePolicy` / `CMD_COOKIE_POLICY` is set to `none` (Otherwise you will get a `AUTH failed: No cookie transmitted` error.) - `csp.allowFraming` / `CMD_CSP_ALLOW_FRAMING` is set to `true` +See also the [configuration docs](/configuration/#web-security-aspects) for more information about these options. + ## I can't upload images or the upload gets stuck This problem is typically accompanied by the error `Invalid URL: /uploads/` in the log and is often caused by a missing `domain` / `CMD_DOMAIN` config option or an incorrect reverse proxy config. From c7d581953cb44cba028479c1b05a5ba2140322ee Mon Sep 17 00:00:00 2001 From: David Mehren Date: Thu, 19 Aug 2021 20:22:17 +0200 Subject: [PATCH 8/8] Add heading to FAQ Signed-off-by: David Mehren --- docs/content/faq.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/content/faq.md b/docs/content/faq.md index c21f0a09d..1e0544cfd 100644 --- a/docs/content/faq.md +++ b/docs/content/faq.md @@ -1,3 +1,5 @@ +# FAQ + This page collects Frequently Asked Questions of the community. If you have any questions that aren't answered here, feel free to ask us on [Matrix][matrix.org-url] or stop by our [community forums][hedgedoc-community].