diff --git a/docs/installation-guide/introduction.md b/docs/installation-guide/introduction.md new file mode 100644 index 0000000..91c06c0 --- /dev/null +++ b/docs/installation-guide/introduction.md @@ -0,0 +1,6 @@ +# How to install duckcloud + +The installation process require several steps: + +- Install the binary +- [Setup a reverse proxy](./proxies/why-use-a-proxy.md) diff --git a/docs/installation-guide/proxies/apache-2.md b/docs/installation-guide/proxies/apache-2.md new file mode 100644 index 0000000..a187376 --- /dev/null +++ b/docs/installation-guide/proxies/apache-2.md @@ -0,0 +1,18 @@ +# Using Apache 2.4 as Reverse Proxy + +!!! tldr "" + Should you experience problems with Apache, we recommend that you ask the Apache community for advice, as we cannot provide support for third-party software and services. + +!!! example + ``` + ProxyPass /api/v1/ws ws://duckcloud.fr:2342/api/v1/ws + ProxyPassReverse /api/v1/ws ws://duckcloud.fr:2342/api/v1/ws + ProxyPass / http://duckcloud:2342/ + ProxyPassReverse / http://duckcloud:2342/ + ProxyRequests off + ``` + +The [official documentation](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html) explains in detail, how to configure Apache Web Server 2.4 to reverse proxy WebSockets. + +!!! example "" + **Help improve these docs!** You can contribute by clicking :material-file-edit-outline: to send a pull request with your changes. diff --git a/docs/installation-guide/proxies/caddy-1.md b/docs/installation-guide/proxies/caddy-1.md new file mode 100644 index 0000000..ed287d1 --- /dev/null +++ b/docs/installation-guide/proxies/caddy-1.md @@ -0,0 +1,22 @@ +# Using Caddy 1 as Reverse Proxy + +!!! tldr "" + Should you experience problems with Caddy, we recommend that you ask the Caddy community for advice, as we cannot provide support for third-party software and services. + +For Duckcloud to work properly, you need to enable websockets and transparent proxying: + +!!! example + ``` + example.com { + proxy / duckcloud:2342 { + websocket + transparent + } + } + ``` + +Please refer to the [official documentation](https://caddyserver.com/v1/docs/websocket) +for further details. + +!!! example "" + **Help improve these docs!** You can contribute by clicking :material-file-edit-outline: to send a pull request with your changes. diff --git a/docs/installation-guide/proxies/caddy-2.md b/docs/installation-guide/proxies/caddy-2.md new file mode 100644 index 0000000..435c27e --- /dev/null +++ b/docs/installation-guide/proxies/caddy-2.md @@ -0,0 +1,21 @@ +# Using Caddy 2 as Reverse Proxy + +!!! tldr "" + Should you experience problems with Caddy, we recommend that you ask the Caddy community for advice, as we cannot provide support for third-party software and services. + +WebSocket proxying automatically works in Caddy 2. There is no need to enable this as necessary for Caddy 1, Apache +and NGINX. In addition, Caddy 2 may [automatically create](https://caddyserver.com/docs/caddyfile/directives/tls) +and update [Let's Encrypt](https://letsencrypt.org/) HTTPS certificates. + +!!! example + ``` + example.com { + reverse_proxy duckcloud:2342 + } + ``` + +Please refer to the [official documentation](https://caddyserver.com/docs/v2-upgrade#proxy) +for further details. + +!!! example "" + **Help improve these docs!** You can contribute by clicking :material-file-edit-outline: to send a pull request with your changes. diff --git a/docs/installation-guide/proxies/haproxy.md b/docs/installation-guide/proxies/haproxy.md new file mode 100644 index 0000000..3bccc6c --- /dev/null +++ b/docs/installation-guide/proxies/haproxy.md @@ -0,0 +1,51 @@ +# Using HAPROXY as Reverse Proxy + +!!! tldr "" + Should you experience problems with Haproxy, we recommend that you ask the Haproxy community for advice, as we cannot provide support for third-party software and services. + +```bigquery +defaults + #Defaults used in frontend and backends + #Defined here to avoid repitition + #Can be overwritten in frontends and/or backends + log global + option logasap + mode http + timeout connect 30000ms + timeout client 30000ms + timeout server 30000ms + timeout tunnel 120000ms + timeout queue 5000ms + +########################################################## + +#Frontend config +frontend fe-duckcloud + #'photo' is the name of the subdomain + #TLS certs should be referenced here, maybe created by dehydrated, certbot, ... + bind *:443 ssl crt /etc/ssl/localcerts/wildcard.example.com.pem + + #SNI-Detection + #Can be removed, if not needed + acl sni_photo hdr(host) -i photo.example.com + #Use Backend if domain (acl is set) detected + use_backend be-duckcloud if sni_photo + + #Every unflagged request goes here, may target to another backend as well + default_backend be-duckcloud + +########################################################## + +#Backend config +#be-duckcloud is the name of the backend referenced in frontend +backend be-duckcloud + retries 3 + option forwardfor + no option httpclose + + #Local Duckcloud-Instance + server photo 127.0.0.1:2342 +``` + +!!! example "" + **Help improve these docs!** You can contribute by clicking :material-file-edit-outline: to send a pull request with your changes. diff --git a/docs/installation-guide/proxies/nginx.md b/docs/installation-guide/proxies/nginx.md new file mode 100644 index 0000000..3a7d790 --- /dev/null +++ b/docs/installation-guide/proxies/nginx.md @@ -0,0 +1,43 @@ +# Using NGINX as Reverse Proxy + +!!! danger "Getting Support" + Since [NGINX](https://www.nginx.com/) is notoriously difficult to configure, we unfortunately can't offer you support in case something isn't working. If you have NGINX related issues such as failed uploads or connection errors, we recommend that you [ask the NGINX community for advice](https://www.nginx.com/support/) or try to [use Caddy 2 as a reverse proxy](caddy-2.md), as it is easier to configure and much more convenient to work with overall. + +This [tutorial](https://www.serverlab.ca/tutorials/linux/web-servers-linux/how-to-configure-nginx-for-websockets/) explains, how to configure NGINX WebSocket connections between your client and backend services. + +!!! example + ``` + http { + server { + listen 80 ssl; + listen [::]:80 ssl; + server_name example.com; + client_max_body_size 500M; + + # With SSL via Let's Encrypt + ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; # managed by Certbot + ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; # managed by Certbot + include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot + ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot + + location / { + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header Host $host; + + proxy_pass http://duckcloud:2342; + + proxy_buffering off; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + + client_max_body_size 500M; + } + } + } + ``` + +At the very least you will need to adapt `server_name` and the `ssl_certificate`/`ssl_certificate_key` paths to match your setup. Please refer to their [official documentation](https://nginx.org/en/docs/) for further details. + +[View "Pitfalls and Common Mistakes" ›](https://www.nginx.com/nginx-wiki/build/dirhtml/start/topics/tutorials/config_pitfalls/) + diff --git a/docs/installation-guide/proxies/why-use-a-proxy.md b/docs/installation-guide/proxies/why-use-a-proxy.md new file mode 100644 index 0000000..f7e804e --- /dev/null +++ b/docs/installation-guide/proxies/why-use-a-proxy.md @@ -0,0 +1,13 @@ +# Why use a Proxy? # + +If you install Duckcloud on a public server outside your home network, **always run it behind a secure +HTTPS reverse proxy**. Your files and passwords will otherwise be transmitted in clear text and can be intercepted +by anyone, including your provider, hackers, and governments. Backup tools and file sync apps may refuse to +connect as well. + +If you don't already have a one setup we advice you to try [Caddy 2](./caddy-2.md). This proxy is the easiest to setup and +handle [automatically create](https://caddyserver.com/docs/caddyfile/directives/tls) +and update [Let's Encrypt](https://letsencrypt.org/) HTTPS certificates. + +!!! example "" + **Help improve these docs!** You can contribute by clicking :material-file-edit-outline: to send a pull request with your changes. diff --git a/docs/user-guide/installation.md b/docs/user-guide/installation.md deleted file mode 100644 index 5ad2824..0000000 --- a/docs/user-guide/installation.md +++ /dev/null @@ -1 +0,0 @@ -# This is were we explain the installation process diff --git a/mkdocs.yml b/mkdocs.yml index 69aaa10..abd6954 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,8 +1,15 @@ site_name: Duckcloud nav: - - User Guide: - - Installation: user-guide/installation.md + - Installation Guide: + - Introduction: installation-guide/introduction.md + - Reverse Proxies: + - Why use a Proxy ?: installation-guide/proxies/why-use-a-proxy.md + - Apache 2.4: installation-guide/proxies/apache-2.md + - Caddy 1: installation-guide/proxies/caddy-1.md + - Caddy 2: installation-guide/proxies/caddy-2.md + - Haproxy: installation-guide/proxies/haproxy.md + - NGINX: installation-guide/proxies/nginx.md - About: - Credits: credits.md - Public License: license/agpl.md @@ -62,3 +69,54 @@ theme: font: text: Roboto code: Roboto Mono + +# MkDocs extensions. +markdown_extensions: + - markdown.extensions.admonition + - markdown.extensions.attr_list + - markdown.extensions.codehilite: + guess_lang: false + - markdown.extensions.def_list + - markdown.extensions.footnotes + - markdown.extensions.meta + - markdown.extensions.toc: + permalink: true + - pymdownx.arithmatex + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.critic + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + options: + custom_icons: + - overrides/.icons + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink: + repo_url_shortener: true + social_url_shortener: true + normalize_issue_symbols: true + user: 'photoprism' + repo: 'photoprism' + - pymdownx.mark + - pymdownx.snippets: + check_paths: true + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + clickable_checkbox: true + - md_in_html + - attr_list + - def_list + - tables + - abbr + - meta