TrueNAS-Compose | Your Docker Stacks for TrueNAS Scale

WARNING: If you installed anything before May 1, 2025, you'll need to start over due to major changes in the dataset and network structure!

Setting Up TrueNAS Before Using Docker Stacks

Before you use this Docker stacks, make sure you have completed the following steps to properly configure TrueNAS:

[ Click to Expand ]

Step 1: Install TrueNAS Scale - Follow the official instructions from the TrueNAS website to install it on your hardware.
Step 2: Extend Session Timeout - Increase the session timeout duration to prevent TrueNAS from logging you out prematurely:
1. Navigate to "System > Advanced Settings > Access" in the TrueNAS interface.
2. Click "Configure".
3. Change the "Session Timeout" default value from "300" to: # This increases the session timeout from '5 minutes' to 1 hour *
4. Click "Save".
Step 3: Configure Console - Ensure that access to your TrueNAS console requires a username and password:
1. Navigate to "System > Advanced Settings > Console" in the TrueNAS interface.
2. Click "Configure".
3. Uncheck "Show Text Console without Password Prompt".
4. Click "Save".
Step 4: Configure Location - Ensure that your regional settings are properly configured:
1. Navigate to "System > General Settings > Location" in the TrueNAS interface.
2. Click "Settings".
3. Change the default settings to match your regional settings and formats.
4. Click "Save".
5. If needed, change the date/time settings in your TrueNAS system's BIOS to match your local date/time. # Correct date/time is crucial for logs and network services to work properly
Step 5: Configure Network - Ensure that your network settings are properly configured:
1. Navigate to "Network > Interfaces" in the TrueNAS interface.
2. Click on the "Edit" button of your network interface to access the interface settings.
3. Uncheck "DHCP".
4. Uncheck "Autoconfigure IPv6".
5. Set the "MTU" to:
6. Set your TrueNAS IP address in the "Aliases" section, in most cases:
7. Click "Save".
8. Click on "Test Changes" and confirm.
9. Access the IP address you set up for TrueNAS and login again to confirm the changes, in most cases:
10. Click on "Go To Network Settings", followed by "Save Changes" and "Save" to confirm.
11. Navigate to "Network > Interfaces" in the TrueNAS interface.
12. Click on the "Edit" button of your network interface to access the interface settings.
13. Delete your TrueNAS IP address from the "Aliases" section.
14. Click "Save". # Don't click on the 'Test Changes' button
15. Click on the "Add" button to add a new network interface.
16. Select "Bridge" from the "Type" dropdown menu to create a virtual Switch.
17. Type "br0" in the "Name" field.
18. Type "vSwitch" in the "Description" field.
19. Uncheck "DHCP".
20. Uncheck "Autoconfigure IPv6".
21. Select your network interface (e.g.: eno1, eth0, etc...) from the "Bridge Members" dropdown menu.
22. Set the "MTU" to:
23. Set your TrueNAS IP address in the "Aliases" section, in most cases:
24. Click "Save".
25. Click on "Test Changes" and confirm.
26. Click on "Save Changes", followed by "Save" to confirm.
27. Navigate to "Network > Global Configuration > Settings" in the TrueNAS interface.
28. Replace "local" in the "Domain" field with your Top Level Domain name (e.g.: example.com) if you own one.
29. Add the following nameservers to the "DNS Servers":
30. Add your router's IP address to the "Default Gateway", in most cases:
31. Click "Save".
32. Navigate to "System > General Settings > GUI > Settings" in the TrueNAS interface.
33. Choose your TrueNAS IP address in "Web Interface IPv4 Address", in most cases:
34. Change your TrueNAS HTTP port in "Web Interface HTTP Port" from 80 to:
35. Change your TrueNAS HTTPS port in "Web Interface HTTPS Port" from 443 to:
36. Check "Web Interface HTTP -> HTTPS Redirect".
37. Check "Show Console Messages".
38. Uncheck "Usage collection".
39. Click "Save".
40. Navigate to "System > Advanced Settings > Sysctl" in the TrueNAS interface.
41. Add the following "Variable=Value" pairs: # Don't copy the '=' sign in between the Variables and their Values
42. Your Sysctl should look like this: # Variables and Values have different fields
43. Click "Save".
Step 6: Configure SSH (optional) - Configure SSH access for your "truenas_admin" account:
1. Copy and paste the following command into your terminal (on your local computer):
2. Press "Enter" to accept the default location:
3. Enter a passphrase for extra security. # This will secure your private key
4. Re-enter the same passphrase to confirm.
5. Navigate to "Credentials > Users" in the TrueNAS web interface.
6. Select your "truenas_admin" account.
7. Click on the "Edit" button.
8. Under "Upload SSH Key", click "Choose File" and select your public key file: # id_ed25519.pub
9. Change the "Shell" to "bash".
10. Click "Save".
11. Navigate to "System > Services" in the TrueNAS web interface.
12. Toggle the "SSH" service to "ON".
13. Toggle the "Start Automatically" option to "ON" to run SSH at every boot.
14. To access your TrueNAS system via SSH, copy and paste the following command into your terminal (on your local computer): # Replace '192.168.1.1' with your TrueNAS IP address
Step 7: Create ZFS Pools - You'll need to create at least one ZFS pool to store your System/Apps data:
1. Navigate to "Storage" in the TrueNAS interface.
2. Click on the "Create Pool" button near the top right.
3. Type "tank" on the "Name" field. # This is the default name used in ZFS documentation and in this guide
4. Check "Encryption" (optional). # You'll need to download and securely store your encryption key, losing it may result in 'PERMANENT DATA LOSS' *
5. If encryption is enabled, confirm that "Encryption is for users storing sensitive data" and click "I Understand".
6. Click "Next".
7. Select your pool "Layout". # Use at least a Mirror configuration and prioritize low-latency, high-performance storage (e.g.: Optane, NVMe) for your System/Apps pool
8. Choose the appropriate "Disk Size".
9. Check "Treat Disk Size as Minimun".
10. Set the "Width". # Use at least two disks per VDEV to ensure redundancy
11. Set the "Number of VDEVs". # More VDEVs generally result in higher IOPS, which are especially important for your System/Apps pool
12. Click "Save And Go To Review".
13. Click on the "Create Pool" button to create your System/Apps pool.
14. Confirm that "The contents of all added disks will be erased" and click "Continue".
15. If needed, refer to the official TrueNAS documentation for detailed guidance on pool creation and best practices. # Or watch this video: https://youtu.be/ykhaXo6m-04
Step 8: Configure Apps' Pool - You'll need to configure your Apps' pool to store your Apps data:
1. Navigate to "Apps > Configuration > Choose Pool" in the TrueNAS interface.
2. Select your TrueNAS Apps' pool name from the list, in most cases:
3. Click "Choose" to save.
Step 9: Install NVIDIA Drivers (optional) - If you have a NVIDIA GPU make sure you install the NVIDIA drivers/runtime:
1. Navigate to "Apps > Configuration > Settings" in the TrueNAS interface.
2. Check "Install NVIDIA Drivers"
3. Click "Save".
Step 10: Configure S.M.A.R.T. Tests - Ensure that you create periodic S.M.A.R.T. tests of your Disks:
1. Navigate to "Data Protection > Periodic S.M.A.R.T. Tests" in the TrueNAS interface.
2. Click "Add".
3. Check "All Disks".
4. Select "SHORT" from the "Type" dropdown menu.
5. Select "Weekly (0 0 * * sun) On Sundays at 00:00 (12:00 AM)" from the "Schedule" dropdown menu. # Or change it to meet your needs
6. Click "Save".
Step 11: Configure ZFS Snapshots - Ensure that you create periodic snapshots of your Apps' pool:
1. Navigate to "Data Protection > Periodic Snapshot Tasks" in the TrueNAS interface.
2. Click "Add".
3. Select your TrueNAS Apps' pool name from the "Dataset" dropdown menu, in most cases:
4. Check "Recursive".
5. Uncheck "Allow Taking Empty Snapshots".
6. Keep the "Schedule" settings at their default values. # Or change them to meet your needs
7. Click "Save".
8. In the future, configure periodic snapshot tasks on the datasets associated with your Docker volumes instead.
Step 12: Configure ZFS Replication (optional) - If you have more than one pool, you can back up your Apps' pool to a different pool:
1. Navigate to "System > Shell" in the TrueNAS interface.
2. Type "cli" and press Enter.
3. Copy and paste the following command into the TrueNAS CLI: # Replace 'backups' with your Backups' pool name
4. Type "exit" and press Enter.
5. Navigate to "Data Protection > Replication Tasks" in the TrueNAS interface.
6. Click "Add".
7. Select your source location: # Replace 'tank' with your Apps' pool name
8. Select your target location: # Replace 'backups' with your Backups' pool name
9. Check "Recursive".
10. Type "tank_backup" in the "Task Name" field.
11. Click "Next".
12. Keep the "Schedule" settings at their default values. # Or change them to meet your needs
13. Click "Save".
14. Click on the "Edit" button of your new replication task.
15. Search for "Destination Dataset Read-only Policy" and change it from "SET" to: # This will preserve your Apps' pool permissions
16. Click "Save".
17. In the future, configure replication tasks on the datasets associated with your Docker volumes instead.

Step 13: Create ZFS Datasets - You'll need to create datasets within your ZFS pools to organize and manage your data:

Navigate to "System > Shell" in the TrueNAS interface.
Type "cli" and press Enter.
Copy and paste the following commands into the TrueNAS CLI: # Replace 'tank' with your Apps' pool name

storage dataset create name=tank/docker share_type=APPS

storage dataset create name=tank/docker/dockge share_type=SMB

storage dataset create name=tank/docker/dockge/stacks share_type=SMB

storage dataset create name=tank/docker/dockge/data share_type=SMB

storage dataset create name=tank/docker/notifications share_type=SMB

storage dataset create name=tank/docker/notifications/diun share_type=SMB

storage dataset create name=tank/docker/notifications/gotify share_type=SMB

Copy and paste the following commands into the TrueNAS CLI: # Replace 'tank' with your Media/Downloads' pool name (it can be your Apps' pool)

storage dataset create name=tank/downloads share_type=APPS

storage dataset create name=tank/media share_type=APPS

storage dataset create name=tank/media/audiobooks share_type=SMB

storage dataset create name=tank/media/books share_type=SMB

storage dataset create name=tank/media/movies share_type=SMB

storage dataset create name=tank/media/music share_type=SMB

storage dataset create name=tank/media/podcasts share_type=SMB

storage dataset create name=tank/media/tvseries share_type=SMB

Copy and paste the following commands into the TrueNAS CLI: # Replace 'tank' with your Data/Games' pool name (it can be your Apps' pool)

storage dataset create name=tank/data share_type=APPS

storage dataset create name=tank/games share_type=APPS

storage dataset create name=tank/games/eggs share_type=SMB

storage dataset create name=tank/games/installers share_type=SMB

storage dataset create name=tank/games/roms share_type=SMB

storage dataset create name=tank/users share_type=SMB

Type "exit" and press Enter.
Navigate to "Datasets" in the TrueNAS interface.
Expand your Apps' pool tree and click on the "docker" dataset to select it.
Navigate to "Permissions > Edit" to access the ACL Editor.
Set the following "Access Control List": # This is the default ACL for Apps (which is applied when you set 'share_type=APPS' during dataset creation)

owner@ - root                               Allow | Full Control
group@ - root                               Allow | Modify
Group - builtin_users                       Allow | Modify
Group - builtin_administrators              Allow | Full Control
User - apps                                 Allow | Modify

Check "Apply permissions recursively" and confirm.
Check "Apply permissions to child datasets".
Click "Save Access Control List".
Repeat steps 7-13 for the "media" and "downloads" datasets (instead off the "docker" dataset), which are located at the root of your Media/Downloads' pool.
Repeat steps 7-13 for the "data" and "games" datasets (instead off the "docker" dataset), which are located at the root of your Data/Games' pool.

Step 14: Create Docker Networks - You'll need to create the "dns", "proxy" and "home" networks to easily access your Docker services:

Navigate to "System > Shell" in the TrueNAS interface.
Copy and paste the following commands into the TrueNAS shell:

sudo docker network create --driver=bridge --subnet=172.17.0.0/24 --ip-range=172.17.0.0/24 --gateway=172.17.0.1 dns

sudo docker network create --driver=bridge --subnet=172.18.0.0/24 --ip-range=172.18.0.0/24 --gateway=172.18.0.1 proxy

sudo docker network create --driver=macvlan --subnet=192.168.1.0/24 --ip-range=192.168.1.0/24 --gateway=192.168.1.254 -o parent=br0 home

If needed, replace the "home" network's subnet, ip-range and gateway to match your TrueNAS network's settings.

Step 15: Install Dockge - Use Dockge to manage all your Docker stacks. To install it:
1. Navigate to "Apps > Discover Apps" in the TrueNAS interface.
2. Search for "dockge" and click to install.
3. Navigate to "Network Configuration" in the installation interface.
4. Keep the default "WebUI Port":
5. Change the "Certificate" to:
6. Navigate to "Storage Configuration" in the installation interface.
7. Choose the following type in "Dockge Stacks Storage":
8. Insert the following path in "Host Path": # Replace 'tank' with your Apps' pool name
9. Choose the following type in "Dockge Data Storage":
10. Insert the following path in "Host Path": # Replace 'tank' with your Apps' pool name
11. Navigate to "Labels Configuration" in the installation interface.
12. Add the following "Key=Value" pairs: # Don't copy the '=' sign in between the Keys and their Values
13. Make sure to set "dockge" in the "Containers" section of each label.
14. Click "Install" and wait for the green "Running" status indicator.
15. Click on the "Web UI" button in the "Application Info" section to open Dockge.
16. Change the URL to "https://" and press Enter. # Add this page to your browser's bookmark bar
17. Set your "Username" and "Password". # Confirm password
18. Click "Create".

Step 16: Install Gotify and DIUN - Use Gotify and DIUN to manage your notifications. To install them:

Click on the "+ Compose" button on Dockge Web interface and type "notifications" on the "Stack Name" field.
Click "Delete" on the "nginx" container.
Copy the notifications stack Docker Compose:

####################################################################################################
# name: NOTIFICATIONS
####################################################################################################

services:

####################################################################################################
# GOTIFY | URL: https://gotify.net
####################################################################################################

  gotify:
    container_name: gotify
    image: gotify/server:latest
    environment:
      - TZ=${TZ:-Europe/Lisbon}
    volumes:
      - /mnt/${APPS_POOL:-tank}/docker/notifications/gotify:/app/data
    networks:
      proxy:
        ipv4_address: 172.18.0.5
      dns:
        ipv4_address: 172.17.0.5
    ports:
      - 31015:80
    dns:
      - 172.17.0.2
    labels:
      - diun.enable=true
      - tsdproxy.enable=true
      - tsdproxy.name=gotify
      - traefik.enable=true
      - traefik.docker.network=proxy
      - traefik.http.routers.gotify.entrypoints=websecure
      - traefik.http.routers.gotify.rule=Host(`gotify.${DOMAIN:-home.arpa}`) || Host(`gotify.ts.${DOMAIN:-home.arpa}`)
      - traefik.http.routers.gotify.tls=true
      - traefik.http.services.gotify.loadbalancer.server.port=80
      #- traefik.http.routers.gotify.middlewares=tinyauth
      #- traefik.http.routers.gotify-ext.entrypoints=websecure-ext
      #- traefik.http.routers.gotify-ext.rule=Host(`gotify.${DOMAIN:-home.arpa}`)
      #- traefik.http.routers.gotify-ext.tls=true
      #- traefik.http.services.gotify-ext.loadbalancer.server.port=80
      #- traefik.http.routers.gotify-ext.middlewares=tinyauth
    restart: unless-stopped

####################################################################################################
# TRUENAS GOTIFY ADAPTER | URL: https://github.com/ZTube/truenas-gotify-adapter
####################################################################################################

  gotify-truenas-adapter:
    container_name: gotify-truenas-adapter
    image: ghcr.io/ztube/truenas-gotify-adapter:main
    environment:
      - GOTIFY_URL=http://172.17.0.48
      - GOTIFY_TOKEN=${TRUENAS_TOKEN}
    network_mode: host
    dns:
      - 172.17.0.2
    labels:
      - diun.enable=true
      - tsdproxy.enable=false
      - traefik.enable=false
    restart: unless-stopped
    depends_on:
      gotify:
        condition: service_started

####################################################################################################
# DOCKER IMAGE UPDATE NOTIFIER | URL: https://crazymax.dev/diun
####################################################################################################

  diun:
    container_name: diun
    image: crazymax/diun:latest
    command: serve
    environment:
      - TZ=${TZ:-Europe/Lisbon}
      - LOG_LEVEL=info
      - DIUN_WATCH_WORKERS=20
      - DIUN_WATCH_SCHEDULE=0 */6 * * *
      - DIUN_WATCH_JITTER=30s
      - DIUN_WATCH_RUNONSTARTUP=true
      - DIUN_PROVIDERS_DOCKER=true
      - DIUN_PROVIDERS_DOCKER_WATCHBYDEFAULT=true
      - DIUN_NOTIF_GOTIFY_ENDPOINT=http://172.17.0.48
      - DIUN_NOTIF_GOTIFY_TOKEN=${DIUN_TOKEN}
      - DIUN_NOTIF_GOTIFY_PRIORITY=1
      - DIUN_NOTIF_GOTIFY_TIMEOUT=10s
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /mnt/${APPS_POOL:-tank}/docker/notifications/diun:/data
    network_mode: host
    dns:
      - 172.17.0.2
    labels:
      - diun.enable=true
      - tsdproxy.enable=false
      - traefik.enable=false
    restart: unless-stopped
    depends_on:
      gotify:
        condition: service_started

####################################################################################################
# NETWORKS
####################################################################################################

networks:
  home:
    external: true
  proxy:
    external: true
  dns:
    external: true

####################################################################################################
# EOF - TrueNAS-Compose - URL: https://www.truenas-compose.com
####################################################################################################

Paste the notifications stack Docker Compose where it says: # Replacing the default

version: "3.8"
services: {}
networks: {}

Copy the notifications stack .env file:

####################################################################################################
# .env - NOTIFICATIONS
####################################################################################################

# GLOBAL:

APPS_POOL=tank # Replace 'tank' with your Apps' pool name

MEDIA_POOL=tank # Replace 'tank' with your Media/Downloads' pool name

DATA_POOL=tank # Replace 'tank' with your Data/Games' pool name

DOMAIN=home.arpa # Replace 'home.arpa' with your Top Level Domain name (e.g.: example.com)

TZ=Europe/Lisbon # Replace 'Europe/Lisbon' with your local time zone

PUID=568 # Default: 568 (Apps)

PGID=568 # Default: 568 (Apps)

####################################################################################################

# GOTIFY:

TRUENAS_TOKEN=truenas_token # Replace 'truenas_token' with your TrueNAS token

DIUN_TOKEN=diun_token # Replace 'diun_token' with your DIUN token

####################################################################################################
# EOF - TrueNAS-Compose - URL: https://www.truenas-compose.com
####################################################################################################

Paste the notifications stack .env file where it says: # Replacing the default

# VARIABLE=value #comment

Edit the .env file to meet your TrueNAS set up if needed. # Ignore "TRUENAS_TOKEN" and "DIUN_TOKEN" for now
Click "Deploy" to install.
Click on the port "31015" in the "gotify" container to access Gotify.
Type "admin" in "Username" and "Password" fields and click "Login". # Default
Navigate to "ADMIN" in Gotify's Web interface, type a "New Password" for the default user and click on "CHANGE".
Navigate to "APPS" in Gotify's Web interface and click on "CREATE APPLICATION" to add TrueNAS as an App.
Type "TrueNAS" in the "Name" field and click "CREATE".
Click on the button to show the token and copy the generated token.
Go back to Dockge's interface and click "Edit" on the notifications stack.
Paste the generated token into the .env file where it says:

TRUENAS_TOKEN=truenas_token

Go back to "APPS" in Gotify's Web interface and click on "CREATE APPLICATION" to add DIUN as an App.
Type "DIUN" in the "Name" field and click "CREATE".
Click on the button to show the token and copy the generated token.
Go back to Dockge's interface and paste the generated token into the .env file where it says:

DIUN_TOKEN=diun_token

Click "Deploy" to redeploy the notifications stack.

Step 17: Install Gotify APP (Android only) - You'll need to install the Gotify app to get notifications:
1. Download and install the latest Gotify app. # https://play.google.com/store/apps/details?id=com.github.gotify
2. Type your "Gotify URL", in most cases: # Replace '192.168.1.1' with your TrueNAS IP address
3. Click "Check URL".
4. Ignore the warning saying "Using HTTP is insecure" and click "I Understand".
5. Type "admin" in the "Username" field and your new password in the "Password" field.
6. Click "Login".
7. Choose a name for your session and click "Create".
8. Enable notifications on your Android device.
Step 18: Configure Alerts - You'll need to configure Gotify alerts to warn you of any issues with your TrueNAS system:
1. Navigate to "System > Alert Settings" in the TrueNAS interface.
2. Click on the "Add" button to add a new alert.
3. Type "Gotify" in the "Name" field.
4. Select "Slack" from the "Type" dropdown menu.
5. Select "Info" from the "Level" dropdown menu. # This will show you all syslog alerts, adjust the level as needed
6. Copy and paste the following URL into the "Webhook URL" field:
7. Click "Send Test Alert" to test the connection. # It will generate a test alert on your Gotify's dashboard (and a notification on your Android device)
8. Click "Save" to confirm.
Step 19: Save Configuration - Ensure that you back up your TrueNAS Scale configuration file: # Do this periodically
1. Navigate to "System > General Settings" in the TrueNAS interface.
2. Click on the "Manage Configuration" dropdown menu and select "Download File".
3. Check "Export Password Secret Seed".
4. Click "Save" to confirm.
Step 20: Reboot - If everything went well, reboot your TrueNAS system.
Step 21: Install OPNsense (optional) - If you have more than one network interface, you can install OPNsense firewall as an Instance: [ Click to Expand ]

Once these steps are completed, you'll be ready to use this Docker stacks on your TrueNAS Scale.

Choose a Docker Stack from the dropdown below to get the Docker Compose and .env File configurations, along with Installation Instructions for TrueNAS Scale.

Docker Stack:

Requires:

Docker Compose

.env File

Installation Instructions for TrueNAS Scale

If you need help (or want to help), feel free to reach out on this thread on the Level1Techs' forum: TrueNAS-Compose