From 98697a341c81a2ab12ea5a58c038de9da23547f9 Mon Sep 17 00:00:00 2001 From: kjeld Schouten-Lebbing Date: Sun, 8 Aug 2021 15:14:36 +0200 Subject: [PATCH] Some initial work on the new quick-start guides and renaming reverse-proxy back to ingress --- .../manual/Quick-Start guides/01-Open-Apps.md | 3 + .../03-Installing-an-App.md | 5 ++ .../Quick-Start guides/04-Edit-an-App.md | 5 ++ .../Quick-Start guides/05-Upgrade-an-App.md | 5 ++ .../Quick-Start guides/06-Rollback-an-App.md | 5 ++ .../Quick-Start guides/07-Deleting-an-App.md | 5 ++ .../08-Dealing-with-Errors.md | 5 ++ .../09-adding-letsencrypt.md | 56 +++++++++++++++++++ .../10-installing-Traefik.md | 5 ++ .../11-traefik-on-port80.md | 5 ++ docs/manual/certificates.md | 55 +----------------- docs/manual/ingress.md | 20 +++++++ docs/manual/reverse-proxy.md | 38 ------------- 13 files changed, 121 insertions(+), 91 deletions(-) create mode 100644 docs/manual/Quick-Start guides/03-Installing-an-App.md create mode 100644 docs/manual/Quick-Start guides/04-Edit-an-App.md create mode 100644 docs/manual/Quick-Start guides/05-Upgrade-an-App.md create mode 100644 docs/manual/Quick-Start guides/06-Rollback-an-App.md create mode 100644 docs/manual/Quick-Start guides/07-Deleting-an-App.md create mode 100644 docs/manual/Quick-Start guides/08-Dealing-with-Errors.md create mode 100644 docs/manual/Quick-Start guides/09-adding-letsencrypt.md create mode 100644 docs/manual/Quick-Start guides/10-installing-Traefik.md create mode 100644 docs/manual/Quick-Start guides/11-traefik-on-port80.md create mode 100644 docs/manual/ingress.md delete mode 100644 docs/manual/reverse-proxy.md diff --git a/docs/manual/Quick-Start guides/01-Open-Apps.md b/docs/manual/Quick-Start guides/01-Open-Apps.md index 0692148455c..86f4157fbfc 100644 --- a/docs/manual/Quick-Start guides/01-Open-Apps.md +++ b/docs/manual/Quick-Start guides/01-Open-Apps.md @@ -3,4 +3,7 @@ When opening the Apps menu item on TrueNAS SCALE for the first time, you get prompted to setup a new pool for Apps. This will create a new dataset on the selected pool called "ix-applications", which will contain all docker containers and most application data, unless specified otherwise. +#### Video Guide + + ![type:video](https://www.youtube.com/embed/YQCKN6Utqss) diff --git a/docs/manual/Quick-Start guides/03-Installing-an-App.md b/docs/manual/Quick-Start guides/03-Installing-an-App.md new file mode 100644 index 00000000000..d05e7a6ea1b --- /dev/null +++ b/docs/manual/Quick-Start guides/03-Installing-an-App.md @@ -0,0 +1,5 @@ +# 03 - + +#### Video Guide + +![type:video](https://www.youtube.com/embed/rfgCkCek7_s) diff --git a/docs/manual/Quick-Start guides/04-Edit-an-App.md b/docs/manual/Quick-Start guides/04-Edit-an-App.md new file mode 100644 index 00000000000..82465f8f041 --- /dev/null +++ b/docs/manual/Quick-Start guides/04-Edit-an-App.md @@ -0,0 +1,5 @@ +# 04 - Editing Apps + +#### Video Guide + +![type:video](https://www.youtube.com/embed/PseYHVlGYxE) diff --git a/docs/manual/Quick-Start guides/05-Upgrade-an-App.md b/docs/manual/Quick-Start guides/05-Upgrade-an-App.md new file mode 100644 index 00000000000..d036dd4cb14 --- /dev/null +++ b/docs/manual/Quick-Start guides/05-Upgrade-an-App.md @@ -0,0 +1,5 @@ +# 05 - Upgrading Apps + +#### Video Guide + +![type:video](https://www.youtube.com/embed/NsZAGtodJVk) diff --git a/docs/manual/Quick-Start guides/06-Rollback-an-App.md b/docs/manual/Quick-Start guides/06-Rollback-an-App.md new file mode 100644 index 00000000000..4af3ed1e9be --- /dev/null +++ b/docs/manual/Quick-Start guides/06-Rollback-an-App.md @@ -0,0 +1,5 @@ +# 06 - App Roleback after an update + +#### Video Guide + +![type:video](https://www.youtube.com/embed/FtfF3rs_YEk) diff --git a/docs/manual/Quick-Start guides/07-Deleting-an-App.md b/docs/manual/Quick-Start guides/07-Deleting-an-App.md new file mode 100644 index 00000000000..4622891d5b7 --- /dev/null +++ b/docs/manual/Quick-Start guides/07-Deleting-an-App.md @@ -0,0 +1,5 @@ +# 07 - Deleting an App + +#### Video Guide + +![type:video](https://www.youtube.com/embed/GpC6x7Xw7-w) diff --git a/docs/manual/Quick-Start guides/08-Dealing-with-Errors.md b/docs/manual/Quick-Start guides/08-Dealing-with-Errors.md new file mode 100644 index 00000000000..1458f258390 --- /dev/null +++ b/docs/manual/Quick-Start guides/08-Dealing-with-Errors.md @@ -0,0 +1,5 @@ +# 08 - Dealing with common Errors + +#### Video Guide + +![type:video](https://www.youtube.com/embed/fc6aDVqX0Zo) diff --git a/docs/manual/Quick-Start guides/09-adding-letsencrypt.md b/docs/manual/Quick-Start guides/09-adding-letsencrypt.md new file mode 100644 index 00000000000..b8742f10e5a --- /dev/null +++ b/docs/manual/Quick-Start guides/09-adding-letsencrypt.md @@ -0,0 +1,56 @@ +# 09 - Adding Lets-Encrypt Certificates + +With TrueNAS SCALE, it's possible to automatically generate certificates for your domain(s) using letsencrypt. However, this process is not very self-explainatory. +After you managed to complete this how-to, you should be able to select "iX Certificate" as certificate option and your personal certificate in the other drop-down box! + +##### Requirements + +To use iX Certificates with letsencrypt there are a few requirements: +- Preferably use a DNS server that doesn't have any caching (no local DNS server) for your TrueNAS system. +- Have an email address entered for your TrueNAS SCALE `root` user. (this email will also be used for letsencrypt reminder!) +- Own a domain name +- Use either Cloudflare or AWS Route53 for your domain. (In case you wonder: Using Cloudflare as DNS provider is free) +- Have an active internet connection so TrueNAS SCALE can contact Cloudflare or AWS to verify your domain ownership + +##### How-To + +- Click `Credentials` in the Left side menu and go the `Certificates` page. + + + + + +- Notice `ACME DNS-Authenticators`, select `Add` besides `ACME DNS-Authenticators` to open the menu for adding your DNS provider for domain verification. + + +- Enter the required information and click `save`. +For Cloudflare you need either a global API-Key or a limited-scope API token. Please refer to cloudflare and/or AWS on how to get the required credentials. + + + + +- Notice `Certificate Signing Requests`, select `Add` besides `Certificate Signing Requests` to open the menu for adding the domain information you want a certificate for. + + + + +- Enter all information required in the wizard and save it. +If you are not sure, the defaults are alsmost always "alright", because most of what you enter here is completely ignored by Letsencrypt. +`Common Name` in this case means `Primary domain name`, whereas `Subject Alternate Names` means `Extra domain names`. + + + + + +- Notice your new `Certificate Signing Request` showing up in the box below `Certificate Signing Requests`. Also notice the small `wrench` icon to the right of your `Certificate Signing Request` + + +- Click the small `wrench` icon, this will open the `Create ACME Certificate` menu. In this menu we can actually request either a real (Production) certificate or a testing (staging) certificate from Letsencrypt. +For clearity, it's advicable to use the same Authenticator for all domain names. However: It's okey to generate both a testing and a staging certificate for the same domain. + +- After saving and awaiting the generation proces, you should end up with another `Certificate Signing Request` and a new `Certificate` under `Certificates`, this new `Certificate Signing Request` is used to renew your `Certificate` in the future and should not be deleted! + + +#### Video Guide + +![type:video](https://www.youtube.com/embed/nAVFL2LYC7U) diff --git a/docs/manual/Quick-Start guides/10-installing-Traefik.md b/docs/manual/Quick-Start guides/10-installing-Traefik.md new file mode 100644 index 00000000000..6a33cde8b95 --- /dev/null +++ b/docs/manual/Quick-Start guides/10-installing-Traefik.md @@ -0,0 +1,5 @@ +# 10 - Installing Traefik + +#### Video Guide + +![type:video](https://www.youtube.com/embed/-H2Maoi9Osg) diff --git a/docs/manual/Quick-Start guides/11-traefik-on-port80.md b/docs/manual/Quick-Start guides/11-traefik-on-port80.md new file mode 100644 index 00000000000..6cfb9a638c5 --- /dev/null +++ b/docs/manual/Quick-Start guides/11-traefik-on-port80.md @@ -0,0 +1,5 @@ +# 11 - Exposing Traefik on port 80/443 + +#### Video Guide + +![type:video](https://www.youtube.com/embed/UHuyn9qCY6g) diff --git a/docs/manual/certificates.md b/docs/manual/certificates.md index 2fb4cd48615..eea500b7d49 100644 --- a/docs/manual/certificates.md +++ b/docs/manual/certificates.md @@ -10,55 +10,8 @@ Please be aware that these certificates are not really secure, but are "good eno ### Lets-Encrypt Certificates -With the current version of TrueNAS SCALE, it's possible to automatically generate certificates for your domain(s) using letsencrypt. However, this process is not very clear, hence we added a short how-to guide on getting up-and-running with TrueNAS SCALE and Letsencrypt. -After you managed to complete this how-to, you should be able to select "iX Certificate" as certificate option and your personal certificate in the other drop-down box! - -##### Requirements - -To use iX Certificates with letsencrypt there are a few requirements: -- Preferably use a DNS server that doesn't have any caching (no local DNS server) for your TrueNAS system. -- Have an email address entered for your TrueNAS SCALE `root` user. (this email will also be used for letsencrypt reminder!) -- Own a domain name -- Use either Cloudflare or AWS Route53 for your domain. (In case you wonder: Using Cloudflare as DNS provider is free) -- Have an active internet connection so TrueNAS SCALE can contact Cloudflare or AWS to verify your domain ownership - -##### How-To - -- Click `Credentials` in the Left side menu and go the `Certificates` page. - - - - - -- Notice `ACME DNS-Authenticators`, select `Add` besides `ACME DNS-Authenticators` to open the menu for adding your DNS provider for domain verification. - - -- Enter the required information and click `save`. -For Cloudflare you need either a global API-Key or a limited-scope API token. Please refer to cloudflare and/or AWS on how to get the required credentials. - - - - -- Notice `Certificate Signing Requests`, select `Add` besides `Certificate Signing Requests` to open the menu for adding the domain information you want a certificate for. - - - - -- Enter all information required in the wizard and save it. -If you are not sure, the defaults are alsmost always "alright", because most of what you enter here is completely ignored by Letsencrypt. -`Common Name` in this case means `Primary domain name`, whereas `Subject Alternate Names` means `Extra domain names`. - - - - - -- Notice your new `Certificate Signing Request` showing up in the box below `Certificate Signing Requests`. Also notice the small `wrench` icon to the right of your `Certificate Signing Request` - - -- Click the small `wrench` icon, this will open the `Create ACME Certificate` menu. In this menu we can actually request either a real (Production) certificate or a testing (staging) certificate from Letsencrypt. -For clearity, it's advicable to use the same Authenticator for all domain names. However: It's okey to generate both a testing and a staging certificate for the same domain. - -- After saving and awaiting the generation proces, you should end up with another `Certificate Signing Request` and a new `Certificate` under `Certificates`, this new `Certificate Signing Request` is used to renew your `Certificate` in the future and should not be deleted! +With the current version of TrueNAS SCALE, it's possible to automatically generate certificates for your domain(s) using letsencrypt. However, this process is not very clear, hence we added a short how-to guide as well. +After you managed to complete this, you should be able to select "iX Certificate" as certificate option and your personal certificate in the other drop-down box! ### Import existing certificates @@ -87,7 +40,3 @@ We sincerely hope iX Systems solves the ACME instabilities with due priority. Sometimes you might notice Traefik ignores your certificate. This is most likely due to the domain on your certificate, being different from the domain you entered into the reverse proxy host box. Traefik requires your certificate to match the domain used for Ingress. This is an upstream design decision and something we can easily and safely disable. - -##### New certificates not showing without refresh - -Currently recently added certificates will not show in the App UI, without hitting the button to refresh the App list. diff --git a/docs/manual/ingress.md b/docs/manual/ingress.md new file mode 100644 index 00000000000..a5118d2f1d7 --- /dev/null +++ b/docs/manual/ingress.md @@ -0,0 +1,20 @@ +# Ingress + +Within TrueCharts our aim is to make it as easy as possible to secure your Apps. To support this we supply a seperate Traefik "ingress" app, which has been preconfigured to provide secure and fast connections. + +To use Traefik as ingress, all you have to do is enable "ingress" in the App of your choice and fill out a little form. +We currently require Traefik to be installed before you enable ingress on your App. + +### Adding Certificates + +To add certificates to Apps, we use the TrueNAS SCALE certificate storage. This means you first need to add Certificates to TrueNAS SCALE, after which you can select them when Installing or Editing your App. + +### Notes + +There are a few highlights to take into account when adding a ingress to an App: + +##### Adding hosts is required + +By default the hosts list is empty, this is due to upstream design choices and is a issue that is yet to be solved upstream. + +However: adding hosts (preferably just one) is required for ANY app to function with a ingress enabled. Apps might not install and throw errors if you do not add any hosts. diff --git a/docs/manual/reverse-proxy.md b/docs/manual/reverse-proxy.md deleted file mode 100644 index 3fda587a6c4..00000000000 --- a/docs/manual/reverse-proxy.md +++ /dev/null @@ -1,38 +0,0 @@ -# Reverse Proxy - -Within TrueCharts our aim is to make it as easy as possible to secure your Apps. To support this we supply a seperate Traefik "Reverse Proxy" app, which has been preconfigured to provide secure and fast connections. - -To use Traefik as a Reverse Proxy, all you have to do is enable "Reverse Proxy" in the App of your choice and fill out a little form. - -## Note - -Currently for charts using common 4.0, we do NOT support Reverse-Proxy/Ingress as it's being completely rewrithen from scratch at the moment. - -### Types of Reverse Proxys - -We currently offer the following types of pre-configured reverse proxies: - -- HTTP - -- HTTP using CRD (Advanced) - -- TCP - -- UDP - -Besides HTTP, all these options, require Traefik to be installed before you enable Reverse Proxy on your App. In many cases, the maintainer of your app has hidden specific settings, like the type of Reverse proxies available, to suit your App. - - -### Adding Certificates - -To add certificates to Apps, we use the TrueNAS SCALE certificate storage. This means you first need to add Certificates to TrueNAS SCALE, after which you can select them when Installing or Editing your App. - -### Notes - -There are a few highlights to take into account when adding a reverse proxy to an App: - -##### Adding hosts is required - -By default the hosts list is empty, this is due to upstream design choices and is a issue that is yet to be solved upstream. - -However: adding hosts (preferably just one) is required for ANY app to function with a reverse proxy enabled. Apps might not install and throw errors if you do not add any hosts.