Getting Started
SCALE Apps is a Helm-Charts-as-Apps tool. However, in contrast to more “premium-grade” solutions like kubeapps, it’s not built by Kubernetes specialists and it does not offer complete freedom to deploy helm charts. Nor can you manually edit Chart-Yaml files manually.
This makes SCALE Apps a great tool for users running a TrueNAS SCALE NAS and running a few applications on it. But makes it less optimal for Advanced users.
Tier
SCALE Apps are what we call a “Tier 3” deployment option. This means that while we expect it to go smoothly, there are likely caveats, limited options and/or we’ve limited staff available to help out users with support. Hence, we would advise a “Tier 2” or “Tier 1” solution instead.
Caveats
SCALE Apps is a pretty limited solution. For normal homelab use, TrueCharts SCALE Apps likely will suffice just fine. But for more advanced setups, as mentioned above, it’s not sufficient. It also adds significant layers of “middleware” between the App GUI and Kubernetes/Helm, which is prone to lead to niche issues that other deployment options do not face.
We also would like to point out that iX-Systems, the creators of TrueNAS SCALE, do not have much kubernetes experience or specialised engineers available. This does affect the quality of the end product.
Hence for chart management our preference would be to use FluxCD instead.
How to Configure
Below you’ll find recommended steps to go from a blank or fresh TrueNAS SCALE installation to using TrueCharts with the best possible experience and performance as determined by the TrueCharts team. It does not replace the application specific guides and/or specific guides on certain subjects (PVCs, VPN, linking apps, etc) either, so please continue to check the app specific documentation and the TrueNAS SCALE specific guides we’ve provided on this website. If more info is needed about TrueNAS SCALE
please check out our introduction to SCALE page.
Requirements
- TrueCharts apps share computing resources with your system. Please review our recommended system requirements.
- Your apps dataset needs to be large enough to store the containers, configuration files, snapshots, and other persistent volume (PVC) data. You can always configure additional storage using HDD pools (e.g. downloads folder) for specific apps later.
- Make sure your SCALE installation has a working storage pool that you’d like to use for TrueCharts. Read more in the SCALE tutorial.
- Make sure you have a working Internet connection and can reach
https://github.com
,https://truecharts.org
, andhttps://tccr.io
from the host system. - Ensure your system time is up to date and you’ve chosen your preferred timezone in your SCALE settings. Apps you install will default to this timezone.
- You are signed into your TrueNAS SCALE WebUI as
root
or as a user that can execute commands withroot
permissions. - Your apps pool and associated datasets must be configured before adding TrueCharts. When opening the Apps menu item on SCALE for the first time, you’ll be prompted to choose a storage pool for your Apps.
Minimal Getting Started Setup with SCALE
- Complete the above requirements
- Add catalog with the following trains:
stable
,premium
,system
-> Adding TrueCharts - Install the following apps from the
system
train with default settings:OpenEBS
Prometheus Operator
Cloudnative-PG Operator
andCert-Manager
Adding TrueCharts
-
Go to the Apps page from the top level SCALE menu
-
Click the Discover Apps button on the Apps page
-
Click the Manage Catalogs link on the Discover Apps page
-
Click Add Catalog
-
After reading the iXsystems notice, click Continue and enter the required information:
- Name:
truecharts
- Repository:
https://github.com/truecharts/catalog
- Preferred Trains:
premium
,stable
andsystem
(type each one manually) - Branch:
main
- Name:
-
Click Save and allow SCALE to refresh its catalog with TrueCharts (this may take a few minutes)
Getting started using Charts with your own Domain
- Steps Above -> Minimal Getting Started with SCALE
- Move TrueNAS Port to 81,444 -> TrueNAS WebUI Instructions
- Add Traefik -> Traefik How-To
- Use Cloudflare for DNS and create API token -> Guide
- Add ClusterIssuer -> Clusterissuer How-to
- Add Blocky -> Blocky Setup Guide
- Setup ingress on each Chart you want to expose -> Configure Ingress using Clusterissuer certs
Full TrueCharts Setup on TrueNAS SCALE
- Everything below (includes the steps listed above and extras like HeavyScript, MetalLB and Authelia)
TrueCharts Trains Overview
TrueCharts has multiple “trains”, or branches of apps which you can choose to install. Below is a summary of each train and its intended use.
stable
contains apps which have been thoroughly tested and expected to be stable and working. Thestable
version of an app is always the best available versionincubator
contains apps which are still in development and/or are not considered to be stable and working well enough to be moved into thestable
branchdependency
contains apps that are mostly used as dependencies. This train is not supported, aside from bug fixespremium
contains apps for core TrueCharts features and, in the future, will be covered by additional support for professional use casessystem
contains operators required for certain apps apps to function at all, recommended leaving thisenabled
.
See here for a list of all apps available for each TrueCharts trains.
HeavyScript
Once you’ve added the TrueCharts catalog, we also recommend installing HeavyScript and configuring it to run nightly with a cron job. HeavyScript is a bash script for managing TrueNAS SCALE applications, automatically updating those applications, backing up applications datasets, opening a shell for containers, and many other features. Please visit the HeavyScript GitHub Page for more info.
OpenEBS Setup
As outlined here, iX-Systems no longer maintains or supports any form of PVC-based storage for apps. For this reason, TrueCharts provides our own OpenEBS storage solution for you to use with our apps. This means you need to install the OpenEBS
app from the TrueCharts system train as below.
-
In the SCALE GUI, go to Apps -> Discover Apps -> Manage Catalogs
-
Ensure you have
system
in the list of Preferred Trains in the TRUECHARTS row as below. If so, skip the next step and proceed to step 4 -
If you don’t already, you can add it by selecting the TRUECHARTS row and selecting the
Edit
button and selectingsystem
under the “Preferred Trains” dropdown list as below -
Create a dedicated, empty dataset on the apps pool you created above, outside of ix-applications. Please ensure you’ve chosen the dataset that’s not inside
ix-applications
. An example “apps” pool layout could look like this where you have a top-level “apps” dataset with “ix-applications” (non-PVC app data) and “pvcApps” (OpenEBS PVC app storage) nested under. -
Then install the
OpenEBS
chart -
Enter the name of the pool and dataset you created earlier in
pool/dataset
format and do not include/mnt/
in front of the pool/dataset, as shown below
It’s important to set the pool/dataset
to the dataset you want to store the folders with the application data in them.
MetalLB installation and disabling integrated LoadBalancer
This step may be optional but is recommended for advanced users and/or those who which to assign specific IPs to their SCALE applications. We have a full guide explaining the setups on the MetalLB-Config Setup Guide page on how to setup MetalLB and disable the integrated LoadBalancer. Please refer to that page for more info.
Prometheus and CNPG system app installations
Many of the popular TrueCharts apps for TrueNAS SCALE rely on Prometheus Operator
and Cloudnative-PG Operator
to be installed PRIOR to installing another app that may rely on functionality these operators provide. If you’re unsure if you’re using any TrueCharts apps that require Prometheus or CNPG functionality, we advise you install these system apps first anyway before attempting to then install any other apps.
Here is a list of apps that rely on CNPG functionality. If you intend to deploy any of these apps, you must install the Cloudnative-PG Operator
app first as above.
If you are migrating from a different CNPG operator, you can use our CNPG Migration Guide for steps on how to install the Cloudnative-PG
operator and migrating to it. We also have this FAQ entry on removing the previous CNPG backend once migrated.
For new users just starting out with TrueNAS SCALE, simply first install Prometheus Operator
followed by Cloudnative-PG Operator
from the TrueCharts Community Catalog before continuing.
Traefik installation for Ingress / Reverse-Proxy support with TrueCharts Apps
Traefik
, our ingress
or reverse-proxy
solution of choice, is integrated into all our apps in order 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. Please check the Traefik
How-To for basic instructions and a video as well.
An optional but extra function enabled by Traefik and supported by many Truecharts Community Catalog apps like Nextcloud
, is the ability to use a middleware
to use your apps remotely. You can setup a basicAuth middleware using our guide Add Traefik Basic Auth to Apps.
Cert-Manager (operator) and Clusterissuer installation for certificate management
TrueCharts only supports the usage of Cert-Manager
(both the operator portion and the main clusterissuer
) for certificate management inside apps for TrueNAS SCALE. The usage of TrueNAS SCALE certificates through the GUI is deprecated and may cease to function in future updates. We highly recommend setting up clusterissuer
using our clusterissuer setup-guide before adding Ingress
to your applications.
Blocky DNS provider for split-DNS installation and guide
Blocky is the optional, but preferred DNS solution for TrueCharts. It’s a DNS proxy, DNS enhancer and ad-blocker which supports “split-DNS” through K8S-Gateway
and is highly-available. The Blocky Setup-Guide will cover basic setup options which will get you up and running and is not all inclusive.
Authelia Installation
Authelia is a Single Sign-On Multi-Factor portal for web apps, and is the preferred solution to secure your TrueCharts apps when exposing them using Traefik
as your ingress solution. We have a detailed guide that goes through setting up Authelia, along with LLDAP as a backend for Authelia and setting up the forwardAuth
section of Traefik to handle the redirections and securing your apps. Please refer to the Authelia Setup-Guide for more info. It is not strictly required, however you are otherwise encouraged to set a very strong password in your previous steps.