TrueNAS Project

A person, who goes by @PapaGigas, has spent an appreciable amount of time defining and publishing a very thorough guide to setting up a TrueNAS server as a complete Home Server. It is good work, but as with all of these projects, is very tailored to his requirements and experience.

The original document is here: TrueNAS-Compose
He also has a discussion board here: Discussion Board

What I Do Like

It is very complete. It starts with setting up the TrueNAS server to be optimized to run Docker. His approach to setting up storage pools and propagating permission is good and works. After the initial configuration and installing the Dockge application which brings along Docker itself, he presents an organized approach to installing groups of applications. The progression is very logical. There are some applications that are necessary, or useful, in order to facilitate installing applications later in the process.

What I Don't Like

His approach is basically a one size fits all. He also assumes that the reader has never touched a TrueNAS system before. He describes each step in great detail even though he has been through it multiple times before. This isn't actually a bad thing but it does get tedious for the more experienced and actually frustrating for people who are are well versed in Linux operations even if they don't know TrueNAS in depth.

For example, while the instructions to open up the Dockge console is fine, once is sufficient. Subsequent times that the step is necessary it could be reduced to "Open the dockge console."

For as much depth as he goes into the minutia, there is no companion documentation about what happens under the covers. Networks ports are defined but extending the overall system is made difficult by some decisions that have been made.

He has a fascination with file systems. He defines file systems not just at the group level, which does make sense, but down to the container level. In some cases, there are multiple file system in play for a single application. This makes no sense to me. I will be flattening out the disk structure to one file system per group. As the members in the stack grow I will create additional stacks but share the original file system. For example, when the media stack becomes difficult to manage I will create a media2 stack bu it will continue to use the media file system.

There is a basic assumption that this system will be dropping into an empty environment. This isn't actually bad, but again someone choosing TrueNAS probably already has a well defined structure in place. The system may not be the only NAS in place. There may already be DNS/DHCP and reverse proxy solutions already in place.

There is no easy way to extend, or even modify, the configuration. The definitions for Pi-Hole and Traefik are literally cooked into final configuration. For Pi-Hole, this means that defining systems in the network outside of this system is quite difficult and time consuming. The way that he has implemented it locks down parts of the UI as a consequence.

While it is great for someone setting things up for the first time, if you already have a Cloudflare/Traefik/Pi-Hole solution that works, casting it aside is not really a option.

Several of the applications use either Maria or Postgres as data stores. There is a fair amount of duplication and overhead doing this. There are also not tools to work directly with the database engines directly. This is a pretty large hole.

Extensions and workarounds

The Environment

Following the system configuration instructions, dockge will be installed in the /mnt/tank/docker/dockge dataset. This location can be changed in the application definition of dockge in TrueNAS apps.Three datasets are defined under that location, data, secrets and stacks. Each stack that is created in the application has a directory under stacks.

Dockge functions as a front end to docker compose and is limited by docker compose constraints. Docker compose limits the location of the .env file to at, or below, the directory of the compose file. If you attempt to put it at some absolute location elsewhere the deployment operation will fail.

Each stack in this project contains an environment section with several common elements. Going through the installation, requires changing some of these elements in each stack. It is possible, and quite easy, to collect the common elements into a single location and then use the env_file directive of compose to pull in that data. It is still necessary to modify the stack to include an env_file definition, but that is a one time activity when defining the stack. For example, the TZ variable can be changed in one location rather than having to it independently in each stack. Also, adding a variable makes it available to all of the stacks without having to change anything else.

It can be argued that this is a trade off of effort. It does require adding the two lines of the env_file directive but saves the time needed to change something in each of the env definitions for each stack. I like the convenience of being able to maintain this information in a single location.

To implement assuming the standard location, the following steps are needed:

1. Create a file called env in /mnt/tank/docker/dockge/stacks. This file will contain all of the common definitions across the stacks. Edit the env file with all of the common definitions.
2. For each stack execute the following commands:
   

 cd [stack]<br
 ln -s ../env env 

1. In stack, edit the container definitions to add the following two lines above the environment directive:
   

 env_file:

   - ./env

1. Deploy, or start, the stack

Since the environment is set during the startup, the environment isn't dynamic. A start, or redeployment, is necessary for the environment change to take effect. Only one option will be offered.

Local environment definitions will override those taken from the file.

Verify that the desired definitions are in effect using Portainer.

Back to: Software on Linux Desktops