Truenas Custom App

TrueNAS Custom App Management Skill

This skill provides expert procedural guidance for deploying, updating, and managing Custom Apps (ix-charts) on TrueNAS Scale using the command line and SSH.

Deploying a New Custom App

Since standard Docker commands are not natively accessible on TrueNAS Scale (which uses k3s), deploying a new custom app typically involves preparing a host path and configuring the app via the TrueNAS Web UI.

1. Prepare the Host Directory:

   • Create a directory on the TrueNAS server for the application code (e.g., /mnt/nasroot/apps/<app-name>).
   • Use rsync or scp to copy the initial application code, requirements.txt, Dockerfile, and other necessary assets to this directory.
   • Note: It is recommended to run the app as a standard non-root user (e.g., apps), so ensure the directory permissions are set appropriately (chown -R apps:apps /mnt/nasroot/apps/<app-name>).

2. Configure in TrueNAS UI:

   • Navigate to Apps > Launch Docker Image (or Discover > Custom App).
   • Set the Application Name (this will be the release name, e.g., <app-name>).
   • Configure the Container Entrypoint & Args to run your startup script or command (e.g., install dependencies and run python).
   • Add Host Path Volumes to mount the directory created in Step 1 to the container (e.g., mount /mnt/nasroot/apps/<app-name> to /app).
   • Configure any necessary Environment Variables and Networking (Port Forwarding).

Updating an Existing Custom App

To update the application code without losing generated data or requiring a full UI reconfiguration:

1. Sync the Updated Code:

   • Use rsync from your local development machine to push changes to the TrueNAS host directory.
   • Crucial: Exclude data directories (e.g., uploads/, outputs/, images/, __pycache__/) to prevent overwriting user data.
   • Example Command:

     rsync -avz --exclude 'static/uploads' --exclude 'static/outputs' --exclude '__pycache__' ./ ssrtist@truenas:/mnt/nasroot/apps/<app-name>/
     

2. Restart the Application:

   • Once the code is synced, restart the TrueNAS custom app to apply the changes.
   • Use the midclt TrueNAS CLI tool to trigger a redeploy of the chart release:

     ssh ssrtist@truenas "sudo midclt call chart.release.redeploy <app-name>"
     

   • Note: Replace <app-name> with the exact release name configured in TrueNAS.

Querying App Status

To check the status of the deployment or view available apps, use:

ssh ssrtist@truenas "midclt call chart.release.query"

You can parse the JSON output to find the pod status and other metadata.