How to Use Docker on TrueNAS Scale

  • Post author:WunderTech
  • Post published:May 25, 2023
  • Post last modified:May 25, 2023
  • Post category:TrueNAS
  • Reading time:12 mins read

In this article, we’re going to take a look at how to use Docker on TrueNAS Scale.

Why Use Docker on TrueNAS Scale?

Using Docker on TrueNAS Scale is a great way to enhance the overall operation of your TrueNAS server. One of the main reasons to use Docker on TrueNAS Scale is the overall flexibility that Docker provides.

Docker allows you to compartmentalize applications into separate containers, each with its own set of resources and dependencies. This means you can run various applications on your TrueNAS Scale server without worrying about compatibility issues or the requirements of one application impacting another’s.

Another reason to use Docker on TrueNAS Scale is the overall ease of deployment and management it provides. Docker containers can be easily installed, updated, and removed without impacting the overall TrueNAS system or other containers.

Finally, Docker has a huge library of ready-to-use images that significantly cut down on the time and effort required for software installation and configuration, which makes it a go-to for many users.

Docker on TrueNAS Scale

There are two main ways to use Docker on TrueNAS Scale. The first utilizes the apps section and the second allows you to create any Docker container you’d like. We’ll take a look at Docker Compose on TrueNAS Scale below as well.

Apps on TrueNAS Scale

The Apps section in TrueNAS Scale allows you to quickly configure an application, but the underlying technology is actually a Docker container.

apps that use docker on truenas scale

Any of the apps in this list can be installed by selecting Install. When you click the install button, a sidebar appears where you can modify specific settings about the container.

example of an app creation.

While it may appear like this is its own application, it’s actually a Docker container. When you configure the application and install it, you’ll notice that the image will be downloaded in the Manage Docker Images section.

docker images.

This is also the location where you can download updates to existing Docker images.

How to Create a Docker Container on TrueNAS Scale

While the applications shown above will allow you to easily create a Docker container using a preset configuration, you can technically create any Docker container you’d like. Since TrueNAS Scale is built on Debian-Linux unlike TrueNAS Core, Docker is supported out of the box.

In order to use Docker on TrueNAS Scale to create containers, follow the steps below.

1. Select Apps, then select Launch Docker Image.

truenas apps tab.

2. A configuration menu will appear where you can modify the settings. By default, nothing will be filled out so when you’re configuring a new Docker container, you must configure all the important settings for each container.

Unfortunately, for this reason, it’s difficult to explain what sections are required as they will differ based on the container. However, here’s an example that shows you how to configure Jellyfin on TrueNAS. I will try and break down some of the important settings as best as I can below.

  • Application Name: Name of the application.
  • Image Repository: The Docker image you’ll be using.
  • Image Tag: The version of the image you’d like to use (most of the time, the latest).
docker settings and application name,
  • Container CMD/Args: Executable commands the container should run when starting. These will vary greatly depending on the container (or may not even be used at all).
container execution commands.
  • Container Environment Variables: The environment variables the container uses. Most containers (though not all) utilize some sort of environment variable to customize the experience or add important parameters.
environment variables in truenas scale.
  • Networking: The entire networking tab will customize the experience of the networking for the container. In this section, you can modify the Host Interface and set up the IPAM Type (static IP or DHCP).
    • In rare circumstances, you might want to modify the DNS Policy or Nameservers, but speaking transparently, this isn’t something I frequently modify.
  • The Port Forwarding section is where you can map container ports to node ports. This section is extremely important if you’d like to modify any ports.
networking settings in truenas scale.
  • Storage: The storage section is frequently modified as you generally want to set up persistent storage for containers (so that if you ever have to move it or even recreate it on the existing TrueNAS setup, all of your settings will be saved).
    • Generally, Host Path Volumes are used, though there are times when Memory Backed Volumes or Volumes should be configured. The paths to use will differ based on the container.
setting up persistent storage in truenas scale.
  • Some of the other settings should be modified depending on the container. This is also where you can enable Privileged Mode if necessary. With that said, you want to avoid running containers with privilege if possible.
additional docker settings and saving/creating a container.

3. When you’ve finished modifying all of the settings, selecting Save will create the container! After a little while, your container should be started and running in the Installed Applications tab.

This is also the location where you can select Web Portal to access the web portal, or start/stop/delete the container!

showing a running docker app in truenas scale.

Docker Compose on TrueNAS Scale

From an official support perspective, the method above is the only way that you can (or should) use Docker on TrueNAS Scale.

Technically speaking, you can use the CLI to create Docker containers, though I strongly urge that you don’t due to the way TrueNAS Scale manages Docker containers.

There is a way to configure Docker Compose on TrueNAS Scale, but it requires you to use a different catalog (TrueCharts). TrueCharts will allow you to install a bunch of different applications or Docker Compose functionality through the Apps tab.

To add the TrueCharts catalog, select Add Catalog, then paste the path below in the Repository section. Give the catalog a name, then Save.

NOTE: As mentioned above, this is not officially supported.
adding truecharts to truenas scale.

After a few minutes, the Truecharts applications will display and you’ll notice that there are a lot more Apps than there used to be. One of those Apps will now be Docker Compose:

docker compose on truenas scale.

While Docker Compose will be installed, please remember that this is not officially supported and you may run into issues. In general, if you can create the Docker container using the TrueNAS GUI, it’s probably in your best interest to do that.

Conclusion: Docker on TrueNAS Scale

While this article looked at how to set up Docker on TrueNAS Scale, the true power comes when actually configuring different containers. Since there are so many different types, the configuration for each will be entirely different. However, it’s a good place to start and hopefully after reading the tutorial above, you’ll be able to implement different containers by using Docker on TrueNAS Scale.

Thanks for checking out the tutorial on Docker on TrueNAS Scale. If you have any questions on Docker on TrueNAS Scale, please leave them in the comments!


Frank is an IT professional with 13+ years experience and the creator of WunderTech. He focuses on sharing his experience with others on computer hardware, servers, software, networking, and self-hosted apps. He has a BS in Computer Information Systems and an MBA. Learn more about Frank in his bio.