scale-catalog/README.md

132 lines
10 KiB
Markdown
Raw Normal View History

2022-01-19 20:14:09 +00:00
# truetool
2022-06-14 08:36:45 +00:00
2022-12-10 13:51:50 +00:00
An easy tool for frequently used TrueNAS SCALE CLI utilities.
2022-01-16 15:15:58 +00:00
2022-12-27 10:43:04 +00:00
Please before using this tool, [read this note](https://truecharts.org/manual/guides/Important-MUST-READ)
2022-07-16 23:26:16 +00:00
2022-06-14 08:36:45 +00:00
## Table of contents:
2022-12-10 13:51:50 +00:00
2022-06-14 08:36:45 +00:00
* [Synopsis](#synopsis)
* [Arguments](#arguments)
* [How to Install](#how-to-install)
* [How to Update](#how-to-update)
* [Creating a Cron Job](#creating-a-cron-job)
* [Additional Information](#additional-information)
<br>
## Synopsis
2022-06-16 10:09:40 +00:00
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.
2022-06-14 08:36:45 +00:00
It also offers a few handy shortcuts for commonly required chores, like: Enabling Apt or Helm
## Arguments
2022-06-16 10:09:40 +00:00
| Flag | Example | Parameter | Description |
| --------------- | ---------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| --delete-backup | --delete-backup | None | Opens a menu to delete backups<br>_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<br>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 |
2022-06-16 10:09:40 +00:00
| --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 |
2022-10-27 22:09:58 +00:00
| -b | -b 14 | Integer | Backup `ix-applications` dataset<br>_Creates backups up to the number you've chosen_ |
2022-06-16 10:09:40 +00:00
| -i | -i nextcloud -i sonarr | String | Applications listed will be ignored during updating<br>_List one application after another as shown in the example_ |
2022-06-16 10:18:17 +00:00
| -v | -v | None | Verbose Output<br> |
2022-06-16 10:09:40 +00:00
| -t | -t 150 | Integer | Set a custom timeout to be used with either:<br>`-m` <br>_Time the script will wait for application to be "STOPPED"_<br>or<br>`-(u\|U)` <br>_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 |
2022-06-14 08:36:45 +00:00
<br>
<br>
## How to Install
2022-01-16 15:15:58 +00:00
2022-06-16 10:15:31 +00:00
### 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
2022-06-14 08:36:45 +00:00
2022-06-16 10:09:40 +00:00
In this example we created a `scripts` dataset on the TrueNAS SCALE system, feel free to use another folder.
2022-06-14 08:36:45 +00:00
2022-06-16 10:15:31 +00:00
##### 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.
2022-06-14 08:36:45 +00:00
### Open a Terminal
**Change Directory to your scripts folder**
2022-06-16 10:09:40 +00:00
2022-06-14 08:36:45 +00:00
```
cd /mnt/pool/scripts
```
**Git Clone truetool**
2022-06-16 10:09:40 +00:00
2022-06-14 08:36:45 +00:00
```
git clone https://github.com/truecharts/truetool.git
```
**Change Directory to truetool folder**
2022-06-16 10:09:40 +00:00
2022-06-14 08:36:45 +00:00
```
cd truetool
```
From here, you can just run truetool with `bash truetool.sh -ARGUMENTS`
<br>
2022-01-16 15:15:58 +00:00
## How to Update
2022-06-14 08:36:45 +00:00
TrueTool updates itself automatically.
<br >
2022-01-16 15:15:58 +00:00
2022-06-14 08:36:45 +00:00
## Creating a Cron Job
2022-06-14 08:36:45 +00:00
1. TrueNAS SCALE GUI
2. System Settings
3. Advanced
4. Cron Jobs
1. Click Add
2022-06-16 10:09:40 +00:00
| 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 |
2022-06-14 08:36:45 +00:00
<br >
<br >
2022-06-14 08:36:45 +00:00
### Additional Information
2022-01-19 20:00:14 +00:00
2022-06-14 08:36:45 +00:00
#### TrueTool vs HeavyScript
2022-12-10 13:51:50 +00:00
TrueTool and HeavyScript are based, in essence, based on the original (python based) TrueUpdate and TrueTool.
2022-06-14 08:36:45 +00:00
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.
2022-06-16 10:09:40 +00:00
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.
2022-01-20 15:00:41 +00:00
2022-06-14 08:36:45 +00:00
From this point onwards the HeavyScript and TrueTool diverged a bit.
2022-06-16 10:09:40 +00:00
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.
2022-06-14 08:36:45 +00:00
But this also means we can give guarantees TrueTool works optimally with our Catalog of TrueNAS SCALE Apps, as well as official Apps.
2022-01-20 15:00:41 +00:00
2022-06-14 08:36:45 +00:00
Users from HeavyScript can safely start using TrueTool, as we've made precautions to ensure the backups take over smoothly.
2022-12-10 13:51:50 +00:00
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.