Restructure the manual between indepth and quickstart info

2021-08-08 15:28:06 +02:00
parent bc11c86ea9
commit 36dd3d127b
7 changed files with 1 additions and 25 deletions
@@ -0,0 +1,42 @@
+# How to: Create Certificates
+
+At TrueCharts we support HTTPS deployments of every app using our Traefik Reverse Proxy. We support both self-signed, custom and lets-encrypt certificates, using the TrueNAS SCALE building certificate manager. Available under "Credentials"
+
+### Self Signed certificates
+
+Self signed certificates are relatively straight forward and handled by Traefik itself. You just select "self signed" when adding a reverse-proxy to your App and Traefik does the rest!
+
+Please be aware that these certificates are not really secure, but are "good enough" for testing.
+
+### 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 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
+
+TrueNAS SCALE also allows you to manually import certificates, this is rather straight forward:
+Copy-Paste the keys into their respective boxes and hit `save`
+
+
+### Notes
+
+There are a few known bugs, issues and/or oddities currently in regards to Certificates
+
+##### Error during certificate creation
+
+ACME (the system doing letsencrypt) is not super stable on TrueNAS SCALE currently. This is a SCALE issue and not (directly) related to TrueCharts.
+We suggest the following steps to limit the chance of errors during certificate creation:
+
+- Use the DNS-Authenticators DNS server as TrueNAS SCALE DNS server under "Networking". For example, for cloudflare this would be `1.1.1.1`
+
+- Use global Cloudflare API keys, not zoned Tokens
+
+- Reboot after ACME errors
+
+We sincerely hope iX Systems solves the ACME instabilities with due priority.
+
+##### Traefik not accepting/using certificates
+
+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.
@@ -0,0 +1,48 @@
+# Clustering
+
+One of the eventual goals of SCALE is to run hyper-converged clusters based on ZFS, Gluster and Kubernetes.
+While this is awesome, we like to highlight 3 ways of using Clustering with TrueCharts Apps in the future.
+
+Currently no clustering is supported with TrueCharts yet, but we already make precautions during our design phase to implement clustering smoothly in the future.
+
+
+
+##### Single-Pod Flexible
+
+These Apps (can) only run a single instance of a pod at a time, so no "high available" setup available. However these Apps can still dynamically moved over to different nodes if a node fails, this should make sure the downtime stays relatively small.
+These apps can also be "spread" over all nodes by kubernetes. This also means it's worth cutting big Single-Pod Apps into multiple smaller deployements, For example: n we prefer to deploy small database servers with every App (as those can more dynamically be spread over multiple nodes) over one Big single-pod Flexbile App.
+
+Some examples of Apps that can not run with more than one pod at a time, even if we wanted to, are:
+
+- Sonarr
+- Lidarr
+- Radarr
+- Plex
+
+
+
+##### Single-Pod non-flexible
+
+These Apps can not be run with more than 1 pod at a time and on the other hand are bound to a node.
+This means: Host-Down? Pod-Down!
+
+Almost always this is caused by Apps being bound to a specific hardware setup.
+
+*Examples:*
+
+- zwavejs2mqtt
+- HomeAssistant (depending on added hardware)
+- Handbrake (depending on added hardware)
+
+
+
+##### High Availability Apps
+
+These Apps are designed to be the most resiliant of all, they can handle node failures and pod failures without any issue, because they always run multiple Pods at once that fill in once pods or nodes start failing.
+
+Because these Apps are also the most complicated of all, we try to limit them to key-area's of the TrueCharts ecosystem that can not be cut into smaller pieces (Single-Pod Flexible) easily. Like: Ingress and Monitoring.
+
+*Examples:*
+
+
+- Traefik
@@ -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.
@@ -0,0 +1,33 @@
+# Linking Apps Together
+
+We often need to connect individual apps together, for example: Sonarr and SABnzbd. This means we first need to know how to reach those Apps.
+
+##### Linking Apps Internally
+
+The backend for TrueNAS SCALE Apps is Kubernetes. Linking apps together in Kubernetes is done slightly differently than in other systems, as you can't point directly to other containers using their IP address.
+
+Instead we need to use their internal(!) domain name. Please beware: this name is only available between Apps and can not be reached from the host/node or your own PC.
+
+The format for internal domain name for the main service is as follows, please replace `$APPNAME` with the name you gave your App when installing.
+
+- `$APPNAME.ix-$APPNAME.svc.cluster.local`
+
+Kubernetes can usually identify the app when omitting `svc.cluster.local` as well:
+- `$APPNAME.ix-$APPNAME`
+
+If you need to reach a different service (which is not often the case!), you need a slightly different format, where `$SVCNAME` is the name of the service you want to reach:
+
+- `$SVCNAME.ix-$APPNAME.svc.cluster.local` or
+- `$SVCNAME.ix-$APPNAME`
+
+##### Example
+
+To reach an app named "sabnzbd" within Sonarr, we can use the following internal domain name:
+
+- `sabnzbd.ix-sabnzbd`
+
+<a href="https://truecharts.org/_static/img/linking/linking-example-sonarrsabnzbd.png"><img src="https://truecharts.org/_static/img/linking/linking-example-sonarrsabnzbd.png" width="100%"/></a>
+
+##### Additional Documentation
+
+For more help troubleshooting DNS resolution in Kubernetes, review the official documentation: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/
@@ -0,0 +1,38 @@
+# Networking
+
+TrueCharts contain a number of networking options, some super-easy, others quite-advanced. In this document we will try to give a general overview what the general configuration options are and what are their downside and upsides.
+
+### General Choices
+
+##### Host Networking
+
+This option is considered to be an advanced option and is rarely needed. It connects the network-stack of the host to the App.
+
+The reason this is not needed in most Apps, is because we already have great options to deal with most forms of network traffic and every maintainer has the goal to make sure you don't need this setting.
+
+Please refer to the documentation of individual Apps or the Support-Discussions section on github, if you think you might need this setting in your specific usecase
+
+##### ClusterIP
+
+The "Basic" network mode, it create a special load-balancer called a "service" thats only available on the internal network between the Apps.
+
+Don't think you can't connect to it though, because our [Reverse proxy](https://wiki.truecharts.org/general/reverse-proxy/) can forward most traffic for you!
+
+##### NodePort
+
+The name already makes clear what this one does: It connect to a port on your node (the PC hosting your App).
+
+Its a special ClusterIP that forwards all traffic from a certain port on your host-system aka "node", directly to the service. However, it's also still a ClusterIP, so it's very well possible to use both the Reverse proxy and the NodePort, just not at the same port.
+
+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
@@ -0,0 +1,67 @@
+# Storage
+
+TrueCharts uses multiple different storage systems:
+
+
+### Storage types
+
+Storage is currently seperated into two types:
+
+1. Integrated Persistent Storage
+2. Custom Storage aka "hostPathMounts"
+
+
+### Integrated Persistent Storage
+
+Integrated Persistent Storage is based around Kubernetes PVC's to integrate as closely as possible into TrueNAS SCALE. They are also heavily preconfigured to work as optimal as possible and provide options for future expansion such as NFS and Gluster options being added.
+
+These storage options inherently are not well suited to being shared with multiple applications.
+
+We currently have the following Storage options for Integrated Persistent Storage storage:
+
+1. Internal
+
+##### Internal
+
+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 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.
+
+hostPathMounts are actually quite simple:
+It mounts a directory from your TrueNAS SCALE system, directly to a directory inside the App you're installing.
+
+
+### Permissions
+
+Permission settings are rather important and are often something that causes issues for users.
+For both Integrated Persistent Storage and Custom storage, we offer special options to automatically set permissions to coincide with your container.
+
+##### Integrated Persistent Storage
+
+These get automatically set to be owned by root:__PGID__
+There are no options available to configure this.
+
+##### Custom app storage aka "hostPathMounts"
+
+We offer an optional automatic set the permissions according to App PGID and PUID.
+
+Setting permissions automatically means we `chown` the folder and all folder within it, to a user and group of your choice.
+However, we only do so when installing or updating an app.
+
+Please be aware that automatically setting ownership/permissions, does mean it overrides your current CHOWN and CHMOD settings. This could break things and yes, it will destroy your system if used carelessly. It's also not wise to enable the automatic permissions on mounted shares from an external system.
+These permission get based on the user and group you enter in the App configuration dialog and default to `568` (the SCALE default Apps user).
+
+
+### Depricated Storage systems
+
+##### ix_volumes
+
+ix_volumes, where the default storage option for every TrueCharts App before 21.04ALPHA. They always got created and used unless "hostPath" was checked.
+ix_volumes where fully managed by TrueNAS SCALE, they got created and destroyed on demand when creating, updating or editing an App.
+But, most importantly, they could be reverted if an upgrade goes wrong. Which makes them an great to use for storing config files.
+
+They are, normally, stored in the following directory:
+`/mnt/poolname/ix-applications/releases/releasename/volumes/ix_volumes/`