# Truenas Custom App

> TrueNAS Custom App Management Skill

- Skill: `ssrtist/truenas-custom-app` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ssrtist/truenas-custom-app`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ssrtist/truenas-custom-app/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ssrtist (https://skillmd.com/u/ssrtist)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ssrtist/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:*
        ```bash
        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:
        ```bash
        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:
```bash
ssh ssrtist@truenas "midclt call chart.release.query"
```
You can parse the JSON output to find the pod status and other metadata.