Doc patches

docs/development/app development/chart-structure.md

@@ -7,22 +7,28 @@ A TrueNAS SCALE chart also has three additional files an `app-readme.md` file th
 There are 2 directories `charts` and `test`, each representing a train. Chart releases created from catalog items in a specific train cannot be moved to another train. Currently only the `charts` train can be used inside the UI.
 
 ```
-charts/ix-chart/<chart version>/
+charts/<train>/<chart name>/
-  app-readme.md            # TrueNAS SCALE Specific: Readme file for display in TrueNAS SCALE UI
   charts/                  # Directory containing dependency charts
   Chart.yaml               # Required Helm chart information file
-  questions.yaml           # TrueNAS SCALE Specific: File containing questions for TrueNAS SCALE UI
   README.md                # Optional: Helm Readme file (will be rendered in TrueNAS SCALE UI as well)
   templates/               # A directory of templates that, when combined with values.yml will generate K8s YAML
   values.yaml              # The default configuration values for this chart
 ```
+
+```
+charts/<train>/<chart name>/
+  app-readme.md            # TrueNAS SCALE Specific: Readme file for display in TrueNAS SCALE UI
+  questions.yaml           # TrueNAS SCALE Specific: File containing questions for TrueNAS SCALE UI
+  ix_values.yaml           # Hidden configuration values when installing using TrueNAS SCALE
+```
+
 *See the upstream Helm chart [developer reference](https://helm.sh/docs/chart_template_guide/) for a complete walk through of developing charts.*
 
 To convert an upstream chart to take advantage of TrueNAS SCALE enhanced UX, first create an `item.yaml` file.
 This file among other catalog item information provides a list of categories that this chart fits into. This helps users navigate and filtering when browsing the catalog UI.
 
 ```
-$ cat charts/ix-chart/item.yaml
+$ cat charts/<train>/<chart name>/SCALE/item.yaml
 categories:
   - generic
 icon_url: "http://ix_url"
@@ -31,7 +37,7 @@ icon_url: "http://ix_url"
 After that create `app-readme.md` file.
 
 ```
-$ cat charts/ix-chart/<chart version>/app-readme.md
+$ cat charts/<train>/<chart name>/SCALE/app-readme.md
 
 iX-chart is a chart designed to let user deploy a docker image in a TrueNAS SCALE kubernetes cluster.
 It provides a mechanism to specify workload type, add external host interfaces in the pods, configure volumes and allocate host resources to the workload.

docs/development/app development/portal.md

@@ -64,3 +64,8 @@ There are also some additional (advanced) options availale, these can be added b
             type: string
             default: "test.com"
 ```
+
+
+##### Known issues
+
+- Portal currently doesn't work (yet) when setting the servicetype to "Loadbalancer"

docs/development/app development/questions-yaml.md

@@ -78,7 +78,7 @@ For (2), system will normalize values or perform some actions as discussed above
 To minimise the maintenance load of our App collection, we always aim to standardise as much as possible. The same goes for questions.yaml. Included here are some code standardised code-snippets that are expected to be included in every App.
 Be aware that sometimes specific functions might or might not completely function. Leaving them out would, however, everely increase the maintenance load and often said functionality will be added in the common-chart later on anyway.
 ##### Groups
-To make sure all apps stay somewhat the same, we use a standardised `groups:` section. Please make sure to use this in your Apps:
+To make sure all apps stay somewhat the same, we use a list of standardised groups for the groups section. Please make sure to use these groups in your Apps:
 ```
 groups:
   - name: "Container Image"
@@ -107,24 +107,22 @@ groups:
 These options are always* included because almost every chart (eventually) has a use for them and/or other parts of the common chart depend on them.
 They are called general options, because they affect the basic functionalities of a chart. For example: Custom User environment variables, permissions and timezones.
 
-*`PUID`, `PGID`, `UMASK` are only included when they are needed. 
+*`PUID`, `PGID`, `UMASK` are only included when they are needed.
 
 ```
-  - variable: timezone
-    group: "Configuration"
-    label: "Timezone"
-    schema:
-      type: string
-      default: "Etc/UTC"
-      $ref:
-        - "definitions/timezone"
-
   - variable: env
     group: "Configuration"
     label: "Image Environment"
     schema:
       type: dict
       attrs:
+        - variable: TZ
+          label: "Timezone"
+          schema:
+            type: string
+            default: "Etc/UTC"
+            $ref:
+        - "definitions/timezone"
         - variable: PUID
           label: "PUID"
           description: "Sets the PUID env var for LinuxServer.io (compatible) containers"
@@ -193,31 +191,19 @@ They are called general options, because they affect the basic functionalities o
           label: "runAsNonRoot"
           schema:
             type: boolean
-            default: false
+            default: true
         - variable: runAsUser
           label: "runAsUser"
           description: "The UserID of the user running the application"
           schema:
             type: int
-            default: 0
+            default: 568
         - variable: runAsGroup
           label: "runAsGroup"
           description: The groupID this App of the user running the application"
           schema:
             type: int
-            default: 0
+            default: 568
-        - variable: supplementalGroups
-          label: "supplementalGroups"
-          description: "Additional groups this App needs access to"
-          schema:
-            type: list
-            default: []
-            items:
-              - variable: Group
-                label: "Group"
-                schema:
-                  type: int
-                  default: 568
         - variable: fsGroup
           label: "fsGroup"
           description: "The group that should own ALL storage."
@@ -234,4 +220,4 @@ They are called general options, because they affect the basic functionalities o
                 description: "OnRootMismatch"
               - value: "Always"
                 description: "Always"
-```
+```

docs/development/app development/storage.md

@@ -56,9 +56,14 @@ Preventing the user to disable them, ensures that users don't (by mistake) remov
               - variable: emptyDir
                 label: "Mount a ramdisk instead of actual storage"
                 schema:
-                  type: boolean
-                  default: false
                   hidden: true
+                  attrs:
+                    - variable: enabled
+                      label: "Enable emptyDir"
+                      schema:
+                        type: boolean
+                        default: false
+                        hidden: true
               - variable: accessMode
                 label: "Access Mode (Advanced)"
                 description: "Allow or disallow multiple PVC's writhing to the same PVC"
@@ -87,7 +92,7 @@ It should always be included in any App, to give users the option to customise t
 ##### Example
 
 ```
-  - variable: additionalAppVolumeMounts
+  - variable: hostPathMounts
     label: "Custom app storage"
     group: "Storage and Devices"
     schema:
@@ -122,12 +127,16 @@ It should always be included in any App, to give users the option to customise t
                   required: true
                   editable: true
               - variable: emptyDir
-                label: "emptyDir"
+                label: "Mount a ramdisk instead of actual storage"
                 schema:
-                  type: boolean
-                  default: false
                   hidden: true
-                  editable: false
+                  attrs:
+                    - variable: enabled
+                      label: Enable emptyDir
+                      schema:
+                        type: boolean
+                        default: false
+                        hidden: true
               - variable: mountPath
                 label: "Mount Path"
                 description: "Path to mount inside the pod"

docs/development/app development/values-yaml.md

@@ -7,7 +7,7 @@ However, we have multiple different values.yaml files, with different goals. Bec
 
 ##### values.yaml
 
-The normal file with default setting in helm charts. However, for our non-library and non-dependency charts, this is not used for TrueCharts. As questions.yaml generates configs on demand (with addition of ix_values.yaml), this file might interfere with some Helm operations combined with the questions.yaml or test_values.yaml systems or cause unexpected behavior if used.
+This file contains the default config when running the App using stock helm (not SCALE). It also gets used for the testingsuite.
 
 ##### ix_values.yaml
 
@@ -39,14 +39,3 @@ image:
 ##
 
 ```
-
-
-##### test_values.yaml
-
-Our Apps often use special features of TrueNAS inside questions.yaml and our charts. However these features are not (always) compatible with stock Helm. Therefore we define a set of seperate "test" values.yaml setting that get used when we run the test CI.
-
-They should, however, be as close as possible to your "actual" default settings in questions.yaml
-
-##### default_values.yaml
-
-This on is the "odd one" of the bunch. We prefer not to use it for actual default, but to store default when porting charts from upstream.

docs/manual/Migration Guides/index.md

@@ -3,7 +3,7 @@
 Sometimes we can not guarantee automatic updating between new versions of our Apps.
 These pages include some common scenario's and give some guidance how to manually move between different versions and Trains.
 
-##### Between Trains
+### Between Trains
 
 An app will always be just in one train. If an App moves to a different train, you will not be able to update automatically
 Our basic guidence for these cases is:
@@ -17,7 +17,17 @@ Our basic guidence for these cases is:
 - Put back all your old files.
 - Re start the new App
 
-##### Between Versions
+### Between Versions
 
 When new versions introduce breaking changes (which would often be major version changes) they might(!) require the user to reinstall.
 However: We often already provide migration scrips and dealth with these issues manually.
+
+##### Common 2.0 -> common 3.0 based Apps
+
+In cases you upgrade to a common 3.0 based app, reinstall is currently required. Please be aware: Installing will nuke your data!
+Be also aware that we do not have common 2.0 based installs available in the version dropdown
+
+##### Common 3.0 -> common 4.0 based Apps
+
+In cases you upgrade to a common 4.0 based app, reinstall is currently required. Please be aware: Installing will nuke your data!
+However: Common 3.0 based Apps are still available to be installed using the version dropdown

docs/manual/general-configuration.md

@@ -1,6 +1,6 @@
 # General Configuration
 
-There are some setting that are always present on every App from TrueCharts.
+These are some common settings you might find on Apps and an explaination of their usecase.
 
 ##### Explaination sheet:
 

docs/manual/networking.md

@@ -28,3 +28,11 @@ There are, however, multiple downsides to using nodeports:
 
 - You can only pick ports above 9000
 - You can not connect two Apps to the same port
+
+##### LoadBalancer
+
+Loadbalancer connects a service targetPort directly to the Host Network. However: it can do so in lower ranges than NodePort, making it a great solution for things like DNS servers.
+
+There are, however, downsides to using LoadBalancer:
+
+- You can not connect two Apps to the same port

docs/manual/reverse-proxy.md

@@ -4,6 +4,10 @@ Within TrueCharts our aim is to make it as easy as possible to secure your Apps.
 
 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:

docs/manual/storage.md

@@ -8,7 +8,7 @@ TrueCharts uses multiple different storage systems:
 Storage is currently seperated into two types:
 
 1. Integrated Persistent Storage
-2. Custom Storage
+2. Custom Storage aka "hostPathMounts"
 
 
 ### Integrated Persistent Storage
@@ -26,15 +26,13 @@ We currently have the following Storage options for Integrated Persistent Storag
 This storage is integrated into TrueNAS SCALE and completely supports reverting upgrades. Thats why this is the default (and only actually supported!) way of storing App configuration files.
 
 
-### Custom Storage
+### Custom app storage aka "hostPathMounts"
 
 Besides the earlier mentioned Integrated Persistent Storage, we also provide the option to mount as many host folders as you want.
 
-Custom storage currently actually quite simple:
+hostPathMounts are actually quite simple:
 It mounts a directory from your TrueNAS SCALE system, directly to a directory inside the App you're installing.
 
-However: We might port this to PVC's in the future, which is not fully decided on yet.
-
 
 ### Permissions
 
@@ -46,7 +44,7 @@ For both Integrated Persistent Storage and Custom storage, we offer special opti
 These get automatically set to be owned by root:__PGID__
 There are no options available to configure this.
 
-##### Custom storage
+##### Custom app storage aka "hostPathMounts"
 
 We offer an optional automatic set the permissions according to App PGID and PUID.