From b74f2d180998649015658029b9de27f0dbc6463b Mon Sep 17 00:00:00 2001 From: kqmaverick <121722567+kqmaverick@users.noreply.github.com> Date: Tue, 10 Dec 2024 05:28:38 -0700 Subject: [PATCH] docs(traefik): update traefik guides (#29795) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Description** Updates traefik guides with yaml examples. ⚒️ Fixes # **⚙️ Type of change** - [ ] ⚙️ Feature/App addition - [ ] 🪛 Bugfix - [ ] ⚠️ Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] 🔃 Refactor of current code **🧪 How Has This Been Tested?** **📃 Notes:** **✔️ Checklist:** - [ ] ⚖️ My code follows the style guidelines of this project - [ ] 👀 I have performed a self-review of my own code - [ ] #️⃣ I have commented my code, particularly in hard-to-understand areas - [ ] 📄 I have made corresponding changes to the documentation - [ ] ⚠️ My changes generate no new warnings - [ ] 🧪 I have added tests to this description that prove my fix is effective or that my feature works - [ ] ⬆️ I increased versions for any altered app according to semantic versioning - [ ] I made sure the title starts with `feat(chart-name):`, `fix(chart-name):` or `chore(chart-name):` **➕ App addition** If this PR is an app addition please make sure you have done the following. - [ ] 🖼️ I have added an icon in the Chart's root directory called `icon.png` --- _Please don't blindly check all the boxes. Read them and only check those that apply. Those checkboxes are there for the reviewer to see what is this all about and the status of this PR with a quick glance._ --- charts/premium/authelia/docs/Setup-Guide.md | 2 +- charts/premium/traefik/docs/how-to.md | 68 ------------------- .../traefik/docs/redirect-regex-middleware.md | 50 ++++++++------ .../traefik/docs/theme-park-middleware.md | 49 +++++++------ .../docs/traefik-basicAuth-middleware.md | 56 ++++++++------- charts/stable/authentik/docs/how_to.md | 2 +- charts/stable/organizr/docs/forward_auth.md | 2 +- charts/stable/paperless-ngx/docs/how-to.md | 2 +- website/src/content/docs/guides/index.md | 4 +- 9 files changed, 95 insertions(+), 140 deletions(-) delete mode 100644 charts/premium/traefik/docs/how-to.md diff --git a/charts/premium/authelia/docs/Setup-Guide.md b/charts/premium/authelia/docs/Setup-Guide.md index f51e27ca463..21497e9a718 100644 --- a/charts/premium/authelia/docs/Setup-Guide.md +++ b/charts/premium/authelia/docs/Setup-Guide.md @@ -98,7 +98,7 @@ ingress: ## Traefik ForwardAuth Setup -- This part is straight forward as long as you have a working `Traefik` install, please see our [How-To](/charts/premium/traefik/how-to) if you need more info on getting that running. +- This part is straight forward as long as you have a working `Traefik` install. - The following is added to `Traefik` `values.yaml`, diff --git a/charts/premium/traefik/docs/how-to.md b/charts/premium/traefik/docs/how-to.md deleted file mode 100644 index 63e32899163..00000000000 --- a/charts/premium/traefik/docs/how-to.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Installing Traefik ---- - -Within TrueCharts, our aim is to make it as easy as possible to secure your Apps. -To support this, we supply a separate Traefik "ingress" app, which has been pre-configured to provide secure and fast connections. - -:::notice - -The current TrueCharts implementation of Traefik doesn't support TCP/UDP Ingress, only HTTP/HTTPS. - -::: - -## How-To - -### TrueNAS WebUI - -In order to set up Traefik, you will be required to change the default TrueNAS WebUI access ports. -These ports are by default set to port `80` for HTTP and port `443` for HTTPS. -This is necessary as we will be setting Traefik up to function as a reverse proxy, and to receive traffic on these host ports. - -In the TrueNAS Menu, navigate to **System Settings** > **General**. Click the **Settings** button at the top right of the GUI component. -Under these **GUI Settings**, change: - -- Web Interface HTTP Port to port `81` -- Web Interface HTTPS Port to port `444`. - -Click **Save** to save your changes. The WebUI will now prompt you to restart the web server service, -after which you will be automatically redirected to your dashboard through one of the new ports. -If you are not prompted to restart the web server service, you may restart the machine and manually navigate -to the WebUI address followed by one of the new ports eg. `truenas.local:81`. - -:::tip - -These are the recommended ports for this procedure. Using different ports may require some -changes to your configuration that are not covered in this tutorial. - -::: - -:::caution - -Do not skip this step. Neglecting to change the default ports active may cause your WebUI to become inaccessible after the following step. -Ensure you are accessing your WebUI from the new ports before proceeding. - -::: - -### Installing the Traefik SCALE App - -:::note - -Traefik is part of the `premium` train, so make sure you have it enabled as specified in the [guide](/. - -::: - -In the TrueNAS Menu, navigate to **Apps** > **Discover Apps**. Use the search bar to search for or manually -find the Traefik app in the list of apps, and click **Install**. - -The setup of Traefik is relatively straight-forward. Most of the settings remain unchanged from default, except for these two: - -- **Application Name**: Enter a name for your app. You may use simply _traefik_ for this field. -- At the bottom, check the warning checkbox. - -Continue to section 12, and select **Next**. Traefik will now be installed. -After installation you can access the Traefik dashboard using your host IP address followed by `:9000`, or by simply clicking `Open` on the application's entry under **Apps** > **Installed Applications**. - -## Video Guide - - diff --git a/charts/premium/traefik/docs/redirect-regex-middleware.md b/charts/premium/traefik/docs/redirect-regex-middleware.md index b114631864a..97992b9f748 100644 --- a/charts/premium/traefik/docs/redirect-regex-middleware.md +++ b/charts/premium/traefik/docs/redirect-regex-middleware.md @@ -4,35 +4,41 @@ title: Redirect Regex The Redirect Regex middleware redirects a request using regex matching and replacement. -In the `Regex` field enter the capturing regex expression -In the `Replacement` enter the URL to redirect to. - ## Creating the middleware on traefik -Edit your existing traefik install (or install fresh if you don't have it installed) +Edit your traefik `values.yaml`. -- Scroll down to `redirectRegex` -- Click Add -- Name: `guacamole-redirect` (Any name you want, remember it, you will need it later) -- Regex: `^https://remote\.domain\.com/?$` -- Replacement: `https://remote.domain.com/guacamole` -- Check `Permanent` -- Click Save - - ![traefik-regex-redirect-fields](./img/traefik-regex-redirect-fields.png) +```yaml +// values.yaml +middlewares: + redirectRegex: + - name: guacamole-redirect + regex: ^https://remote\.domain\.com/?$ + replacement: https://remote.domain.com/guacamole + permanent: true +``` This will capture `https://remote.domain.com` or `https://remote.domain.com/` and redirect it to `https://remote.domain.com/guacamole` ## Applying the regex redirect middleware to the app -Edit your existing _App_, in this example we will use `guacamole-client`. +Edit your app `values.yaml`. -- Scroll down to `Traefik MIddlewares` (Remember, you need to have `ingress` enabled) -- Click Add -- Name: `guacamole-redirect` (Replace with the name you gave to your middleware on the previous step) -- Click Save - - ![traefik-regex-redirect-app](./img/traefik-regex-redirect-app.png) - -You are ready! +```yaml +// values.yaml +ingress: + main: + enabled: true + integrations: + traefik: + enabled: true + middlewares: + - name: guacamole-redirect + namespace: traefik + certManager: + enabled: true + certificateIssuer: domain-0-le-prod + hosts: + - host: remote.domain.com +``` diff --git a/charts/premium/traefik/docs/theme-park-middleware.md b/charts/premium/traefik/docs/theme-park-middleware.md index 2ea530833aa..a6bd23fe062 100644 --- a/charts/premium/traefik/docs/theme-park-middleware.md +++ b/charts/premium/traefik/docs/theme-park-middleware.md @@ -7,22 +7,22 @@ into [supported apps](https://docs.theme-park.dev/themes). So let's see how to do that. -Note that this will only work on apps you have enabled `ingress`, and only when accessing them via the URL. +Note that this will only work on apps you have enabled traefik intergration, and only when accessing them via the URL. Will NOT work if you access them via `IP:PORT`. ## Creating the middleware on traefik -Edit your existing traefik install (or install fresh if you don't have it installed) +Edit your traefik `values.yaml`. -- Scroll down to `theme.park` -- Click Add -- Name: `guactheme` (Any name you want, remember it, you will need it later) -- App Name: `guacamole` (Replace with the name of the app you want to theme) -- Theme Name: `plex` (Replace wit the theme you want to apply) -- Base URL: (Leave the default, unless you plan to use a self hosted theme provider) -- Click Save - - ![traefik-theme-fields](./img/traefik-theme-fields.png) +```yaml +// values.yaml +middlewares: + themePark: + - name: guactheme + app: guacamole + theme: plex + baseUrl: https://theme-park.dev +``` > Keep in mind that if you decide to use a self hosted theme provider, it will need to have enabled ingress. > Also use the external URL, not the internal, as the client will need to access that theme provider to fetch the @@ -30,16 +30,25 @@ Edit your existing traefik install (or install fresh if you don't have it instal ## Applying the theme to the app -Edit your existing _App_, in this example we will use `guacamole-client`. +Edit your app `values.yaml`. -- Scroll down to `Traefik MIddlewares` (Remember, you need to have `ingress` enabled) -- Click Add -- Name: `guactheme` (Replace with the name you gave to your middleware on the previous step) -- Click Save - - ![traefik-theme-app](./img/traefik-theme-app.png) - -You are ready! +```yaml +// values.yaml +ingress: + main: + enabled: true + integrations: + traefik: + enabled: true + middlewares: + - name: guactheme + namespace: traefik + certManager: + enabled: true + certificateIssuer: domain-0-le-prod + hosts: + - host: remote.domain.com +``` | Before | After | | :-----------------------------------------------------: | :---------------------------------------------------: | diff --git a/charts/premium/traefik/docs/traefik-basicAuth-middleware.md b/charts/premium/traefik/docs/traefik-basicAuth-middleware.md index b586d9e55d8..8b3bb447c2c 100644 --- a/charts/premium/traefik/docs/traefik-basicAuth-middleware.md +++ b/charts/premium/traefik/docs/traefik-basicAuth-middleware.md @@ -2,46 +2,54 @@ title: Add Traefik Basic Auth to Apps --- -Our `traefik` chart has the ability to add various `middlewares` to the chart that can add extra functionality to your setup. You can see the full list of `middlewares` inside the `traefik` menu options. In this guide we'll go over setting up the `Basic Auth` traefik middleware. - -## Prerequisites - -- Traefik installed (see previous steps of `SCALE Apps Manual`) +Our `traefik` chart has the ability to add various `middlewares` to the chart that can add extra functionality to your setup. In this guide we'll go over setting up the `Basic Auth` traefik middleware. ## Installation -Once `traefik` is installed, scroll down to the `Middlewares` section +Edit your traefik `values.yaml`. -![BasicAuth](./img/BasicAuth.png) +```yaml +// values.yaml +middlewares: + basicAuth: + - name: basic + users: + - username: someuser + password: somepassword + - username: seconduser + password: secondpassword +``` -When there, you can fill out the `Configure basicAuth` section with what follows: - -- Name the `basicAuth`, most people choose `basic` - Add as name users as necessary, choosing a specific `Username` and `Password` for each user. ## Adding it to Apps using Ingress -Once you have your `basicAuth` setup, you need to add it to apps that have `Ingress`(Traefik) enabled, otherwise you cannot use this middleware. +Edit your app `values.yaml`. -![EnabledIngress](./img/IngressEnabled.png) - -Scroll to the section `Configure Traefik Middlewares` - -- Click `Add` to add a fillable section -- Write in the name of the `basicAuth` from before. For most people that's basic as the example below. - -![ConfigureTraefikMiddlewares](./img/ConfigureTraefikMiddlewares.png) +```yaml +// values.yaml +ingress: + main: + enabled: true + integrations: + traefik: + enabled: true + middlewares: + - name: basic + namespace: traefik + certManager: + enabled: true + certificateIssuer: domain-0-le-prod + hosts: + - host: app.domain.tld +``` ## Verify Authentication -Once the `basicAuth` is installed, please visit the `URL` that you configured the `Ingress` for. If everything is setup correctly you should see the Pop-Up below. +Once the `basicAuth` is setup, please visit the `URL` that you configured the `Ingress` for. If everything is setup correctly you should see the Pop-Up below. ![BasicAuthWorking](./img/BasicAuthWorking.png) -## Video Guide - - - ## Support - If you need more help you can also reach us using [Discord](https://discord.gg/tVsPTHWTtr) for real-time feedback and support. diff --git a/charts/stable/authentik/docs/how_to.md b/charts/stable/authentik/docs/how_to.md index 8a1162f5440..34613e624c2 100644 --- a/charts/stable/authentik/docs/how_to.md +++ b/charts/stable/authentik/docs/how_to.md @@ -12,7 +12,7 @@ This can be applied to other systems but this specific guide has been tested and ## Prerequisites -This guide assumes you're using Traefik as your Reverse Proxy / Ingress provider and have through the configuration listen in our [Quick-Start guides](/ and/or the [Traefik documents](/charts/premium/traefik/how-to/). Please ensure that you can access your domain properly with Ingress before attempting any further steps. +This guide assumes you're using Traefik as your Reverse Proxy / Ingress provider and have through the configuration listen in our [Quick-Start guides]. Please ensure that you can access your domain properly with Ingress before attempting any further steps. ## Authentik Chart Setup diff --git a/charts/stable/organizr/docs/forward_auth.md b/charts/stable/organizr/docs/forward_auth.md index ce504109da4..e501991d20a 100644 --- a/charts/stable/organizr/docs/forward_auth.md +++ b/charts/stable/organizr/docs/forward_auth.md @@ -12,7 +12,7 @@ Basic setup guide for enabling Organizr authentication on your apps using Traefi ## Prerequisites This guide assumes you're using Traefik as your Reverse Proxy / Ingress provider and have through the configuration listed in our -[Quick-Start guides](/ and/or the [Traefik documents](/charts/premium/traefik/how-to). +[Quick-Start guides]. Please ensure that you can access your domain properly with Ingress before attempting any further steps. ## Organizr App Setup diff --git a/charts/stable/paperless-ngx/docs/how-to.md b/charts/stable/paperless-ngx/docs/how-to.md index 120276520d5..1b6104dac34 100644 --- a/charts/stable/paperless-ngx/docs/how-to.md +++ b/charts/stable/paperless-ngx/docs/how-to.md @@ -31,7 +31,7 @@ online archive. Our app is a simple way to install it on your TrueNAS SCALE serv installation, you can change them later in the app. - Enter the URL your Paperless-ngx will be accessible under in `PAPERLESS_URL` if you plan on making your app accessible from the web. -- If you have set up [Traefik](/charts/premium/traefik/how-to/) for ingress click `Enable Ingress` and enter your +- If you have set up Traefik for ingress click `Enable Ingress` and enter your Paperless-ngx domain in the Hosts section. ![Configure paperless-ngx](./img/configure_paperless-ngx.png) diff --git a/website/src/content/docs/guides/index.md b/website/src/content/docs/guides/index.md index fda4f51f0b3..b5027792767 100644 --- a/website/src/content/docs/guides/index.md +++ b/website/src/content/docs/guides/index.md @@ -26,7 +26,7 @@ To configure MetalLB, you will need to also add `metallb-config` and adapt it to - Steps Above -> [Minimal Getting Started](#minimal-getting-started-setup) - Install the `traefik-crds` chart -- Install `traefik` -> [Traefik How-To](/charts/premium/traefik/how-to) +- Install `traefik` chart - Use CloudFlare for DNS and create an API token -> [Guide](/charts/premium/clusterissuer/how-to#configure-acme-issuer) - Install `Clusterissuer` and configure it for your needs -> [Clusterissuer How-to](/charts/premium/clusterissuer/how-to) - Add `Blocky` and configure it with k8s-gateway enabled -> [Blocky Setup Guide](/charts/premium/blocky/setup-guide) @@ -54,7 +54,7 @@ Many of the popular TrueCharts charts rely on `Prometheus Operator` and `Cloudna ![Traefik](./img/icons/traefik.png) -`Traefik` is our "ingress" or "reverse-proxy" solution of choice and is integrated into all our charts in order to make it as easy as possible to secure your charts. To support this, we supply a separate Traefik "ingress" app, which has been pre-configured to provide secure and fast connections. Please check the `Traefik` [How-To](/charts/premium/traefik/how-to) for basic instructions and a video as well. +`Traefik` is our "ingress" or "reverse-proxy" solution of choice and is integrated into all our charts in order to make it as easy as possible to secure your charts. To support this, we supply a separate Traefik "ingress" app, which has been pre-configured to provide secure and fast connections. An optional but extra function enabled by Traefik and supported by many Truecharts Charts like `Nextcloud`, is the ability to use a `middleware` to use your charts remotely. You can setup a basicAuth middleware using our guide [Add Traefik Basic Auth to Charts](/charts/premium/traefik/traefik-basicauth-middleware/).