scale-catalog/README.md

truetool

An easy tool for frequently used TrueNAS SCALE CLI utilities.

Please before using this tool, read this note

Table of contents:

• Synopsis
• Arguments
• How to Install
• How to Update
• Creating a Cron Job
• Additional Information

Synopsis

TrueTool is a command line tool, designed to enable some features of TrueNAS SCALE that are either not-enabled by default or not-available in the Web-GUI. It also offers a few handy shortcuts for commonly required chores, like: Enabling Apt or Helm

Arguments

Flag	Example	Parameter	Description
--delete-backup	--delete-backup	None	Opens a menu to delete backups Useful if you need to delete old system backups or backups from other scripts
--restore	--restore	None	Restore TrueTool specific ix-applications dataset snapshot
--mount	--mount	None	Initiates mounting feature Choose between unmounting and mounting PVC data
--dns	--dns	None	list all of your applications DNS names and their web ports
--list-backups	--list-backups	None	Prints a list of backups available
--helm-enable	--helm-enable	None	Enables Helm command access on SCALE
--kubeapi-enable	--kubeapi-enable	None	Enables external access to Kuberntes API port
--apt-enable	--apt-enable	None	Enables Apt command access on SCALE
--no-color	--no-color	None	Disables showing colors in terminal output, usefull for SCALE Email output
-U	-U	None	Update applications, ignoring major version changes
-u	-u	None	Update applications, do NOT update if there was a major version change
-b	-b 14	Integer	Backup ix-applications dataset Creates backups up to the number you've chosen
-i	-i nextcloud -i sonarr	String	Applications listed will be ignored during updating List one application after another as shown in the example
-v	-v	None	Verbose Output
-t	-t 150	Integer	Set a custom timeout to be used with either: -m Time the script will wait for application to be "STOPPED" or -(u|U) Time the script will wait for application to be either "STOPPED" or "ACTIVE"
-s	-s	None	Sync Catalogs prior to updating
-p	-p	None	Prune old/unused docker images

How to Install

oneliner

curl -s https://raw.githubusercontent.com/truecharts/truetool/main/bootstrap | bash

You can now use truetool anywhere truetool -ARGUMENTS

Manual Install

Choose a folder

It's important to save the script in a folder that is persistent across TrueNAS System Updates. This saves you from reinstalling or experiencing an accidental lack-of-backups after an update.

New dataset

In this example we created a scripts dataset on the TrueNAS SCALE system, feel free to use another folder.

Root folder

The /root folder houses files for the root user. It's also persistent across updates and hence can be safely used for storing the script.

Open a Terminal

Change Directory to your scripts folder

cd /mnt/pool/scripts

Git Clone truetool

git clone https://github.com/truecharts/truetool.git

Change Directory to truetool folder

cd truetool

From here, you can just run truetool with bash truetool.sh -ARGUMENTS

How to Update

TrueTool updates itself automatically.

Creating a Cron Job

1. TrueNAS SCALE GUI
2. System Settings
3. Advanced
4. Cron Jobs
   1. Click Add

Name	Value	Reason
Description	TrueTool Update apps	This is up to you, put whatever you think is a good description in here
Command	bash /PATH/TO/truetool_DIRECTORY/truetool.sh --no-color -b 14 -sup	This is the command you will be running on your schedule, example: bash /mnt/speed/scripts/truetool/truetool.sh -b 14 -sup
Run As User	root	Running the script as root is REQUIRED. You cannot access all of the kubernetes functions without this user.
Schedule	Up to you, example: 0400	Again up to you
Hide Standard Output	False or Un-ticked	It's best to keep an eye on updates and enable this to receive email reports
Hide Standard Error	False or Un-ticked	We definitely want to see what errors occurred during updating
Enabled	True or Ticked	This will Enable the script to run on your schedule

Additional Information

TrueTool vs HeavyScript

TrueTool and HeavyScript are based, in essence, based on the original (python based) TrueUpdate and TrueTool. Then Support-Manager for TrueCharts, HeavyBullets8, ported this to Bash and started adding some additional logic and options for tasks we frequently needed our users to do, such as mounting PVC's.

After a month or so, the TrueCharts Team officially started refactoring this expanded bash-port. Due to personal reasons, HeavyBullets by then decided to separate from TrueCharts after merging the TrueCharts refactor into his own work. The beauty of OpenSource.

From this point onwards the HeavyScript and TrueTool diverged a bit. We internally review changes within our staff team, to verify we somewhat stick to best-practices. This means, in some cases, we decided not to port certain features from HeavyScript and did decide to add features we think are useful and safe. But this also means we can give guarantees TrueTool works optimally with our Catalog of TrueNAS SCALE Apps, as well as official Apps.

Users from HeavyScript can safely start using TrueTool, as we've made precautions to ensure the backups take over smoothly. We, however, do not advise using HeavyScript with TrueCharts Apps. Not because it's a bad App, but because we offer an alternative that is validated by our Staff.