Heavybullets8 / heavy_script

Bash script for managing Truenas SCALE applications, automatically update applications, backup applications datasets, open a shell for containers.

HeavyScript

Contact

If you have questions or would like to contribute, I have a sub discord category hosted on the Truecharts Discord.

https://discord.gg/tVsPTHWTtr

Table of contents:

Click to expand

• The Menu
• Arguments
  • App
  • Backup
  • DNS
  • Git
  • Pod
  • PVC
  • Self-Update
  • Sync
  • Update
• How to Install
• How to Update
• Configuration File
• Cron Jobs

---

The Menu

Access this with heavyscript

---

Arguments

App

heavyscript app [Flag]

Flag	Example	Parameter	Description
-s --start	-s --start	[Optional: app name]	Start an application.
-x --stop	-x --stop	[Optional: app name]	Stop an application.
-r --restart	-r --restart	[Optional: app name]	Restart an application.
-d --delete	-d --delete	[Optional: app name]	Delete an application.

Backup

heavyscript backup [Flag]

Flag	Example	Parameter	Description
-c [number] --create [number]	-c 15 --create 15	Integer	Create a backup with the specified retention number.
-r --restore	-r --restore		Restore a backup.
-d --delete	-d --delete		Delete a backup.

DNS

heavyscript dns [Optional App Name(s)]

Pass an optional app name to display DNS information for that specific app.

If no app name is provided, it will show internal DNS addresses for all services.

Example:

heavscript dns sonarr radarr nextcloud

Enable

heavyscript enable [Flag]

Flag	Example	Description
--api	--api	Enables external access to the Kubernetes API server.
--apt	--apt	Enable apt, apt-get, and apt-key.
--helm	--helm	Enable helm commands.

Git

heavyscript git [Flag]

Flag	Example	Description
-b --branch	-b --branch	Choose a branch or tag for HeavyScript to use
-g --global	-g --global	Add the script to the global path.

Pod

heavyscript pod [Flag]

Flag	Example	Description
-l --logs	-l --logs	Display container logs.
-s --shell	-s --shell	Open a shell for the container.

PVC

heavyscript pvc [Optional Flag]

Flag	Example	Description
-m --mount	-m --mount	Open a menu to mount PVCs.
-u --unmount	-u --unmount	Unmount all mounted PVCs.

Self-Update

heavyscript self-update

Flag	Example	Description
--major	--major	Includes major updates when self-updating

Sync

heavyscript sync

Syncs the catalog.

Update

heavyscript update [Flags]

Flag	Example	Parameter	Description
-a --include-major	-a --include-major		Update the application even if it is a major version update
-b --backup	-b 14 --backup 14	Integer	Take a backup, and set the number of backups to keep
-c --concurrent	-c 5 --concurrent 5	Integer	How many applications to concurrently update (default: 1)
-i --ignore	-i nextcloud,sonarr -i sonarr --ignore nextcloud --ignore sonarr	String	Ignore updating the specified application
-I --ignore-img	-I --ignore-img		Ignore container image updates
-p --prune	-p --prune		Prune unused images after the update
-r --rollback	-r --rollback		Roll back to the previous version if update failure
-s --sync	-s --sync		Sync the catalog prior to updating applications
-u --update-only	-u nextcloud,sonarr --update-only nextcloud	String	Only update the specified application(s)
-x --stop	-x --stop		Stop the application prior to updating (Not recommended)
-t --timeout	-t 500 --timeout 500	Integer	Set the timeout for the update process in seconds (default: 500)
-U --self-update	-U --self-update		Update HeavyScript itself prior to updating
-v --verbose	-v --verbose		Display verbose output

---

How to Install

HeavyScript can be installed in two different ways depending on your needs and privileges on the system:

Option 1: Non-Privileged Install (Regular User)

This installation method is suitable if you don't have root access or prefer not to install HeavyScript with elevated privileges.

Installation Command:

curl -s https://raw.githubusercontent.com/Heavybullets8/heavy_script/main/functions/deploy.sh | bash && source "$HOME/.bashrc" 2>/dev/null && source "$HOME/.zshrc" 2>/dev/null

What This Does:

• Downloads and places HeavyScript in your user directory.
• Makes HeavyScript executable.
• Allows you to run HeavyScript from any directory using heavyscript.

Note:

• Without root privileges, the script will not create a system-wide symlink in /usr/local/bin.
• You might see a warning message indicating the lack of root privileges. You can proceed without root access, but you'll need to run HeavyScript with root privileges at least once to create the system-wide symlink, if required.

Option 2: Privileged Install (Root or Sudo)

If you have root access or can use sudo, this method will set up HeavyScript for all users on the system.

Installation Command:

curl -s https://raw.githubusercontent.com/Heavybullets8/heavy_script/main/functions/deploy.sh | sudo bash && source "$HOME/.bashrc" 2>/dev/null && source "$HOME/.zshrc" 2>/dev/null

What This Does:

• Installs HeavyScript with root privileges.
• Creates a system-wide symlink in /usr/local/bin, making HeavyScript accessible to all users.
• Downloads and places HeavyScript in the root directory (/root).
• Makes HeavyScript executable and accessible system-wide.

Note:

• This method requires root access or sudo privileges.
• It's recommended for environments where HeavyScript needs to be accessible to multiple users.

---

Choosing the Right Option:

• Non-Privileged Install: Choose this if you're more concerened with security and want to keep HeavyScript isolated to your user account, at least during the initial setup.
• Privileged Install: Choose this if you are less concerened about security and want to make HeavyScript accessible to all users on the system, including the root and sudo user.

---

How to Update

While Updating

heavyscript update --self-update [OPTIONS]

Direct

heavyscript self-update

self-update will update HeavyScript to the latest release, regardless of the branch or tag you're on, and allows you to use any other arguments.

---

Configuration File

Purpose

The configuration file is generated the first time the script is run. You can edit it using nano:

nano ~/heavy_script/config.ini

Modifications in the config file will become the script's defaults.

For example, if you set sync to true under the [UPDATE] section, running heavyscript update will sync the catalog without specifying --sync or -s in the CLI.

Disabling the Configuration

To disable the configuration for a specific run of the script, use:

heavyscript --no-config

This will ignore the configuration file for that run.

---

Cron Jobs

How to Create a Cron Job

To automate tasks using HeavyScript, you can create a cron job. Here's how to set it up in TrueNAS SCALE:

1. Navigate to the TrueNAS SCALE GUI.
2. Go to System Settings > Advanced.
3. Click on Cron Jobs.
4. Click Add to create a new cron job.

Important Note on the Command Path

The command for the cron job should use the full path to the heavy_script.sh file. This path depends on the user who installed HeavyScript. For instance, if you installed HeavyScript as a non-root user, replace /root with your home directory path.

You can find your home directory path by running echo $HOME in the terminal.

Cron Job Settings

• Command: Use the full command with the correct path, as shown in the examples above. The bash prefix and the full path are required for proper execution.
• Run as: Use root, the extra permissions are required for most heavyscript functions.
• Schedule: Choose the frequency and time for the script to run. For example, daily at 4:00 AM.
• Hide Standard Output/Error: Uncheck these options if you wish to receive email notifications about the cron job's output and errors.

My Personal Cron Job

Here's an example of how I set up my personal cron job:

bash /root/heavy_script/heavy_script.sh update --backup 14 --concurrent 10 --prune --rollback --sync --self-update

Remember to adjust the path in the command based on where HeavyScript is installed and the user account used for installation.