Discontent

It was getting to be time to decommission an old Mac mini that we use as a DVR and media server, and so I checked prices of new Macs and bought some NAS hardware instead. At the same time I ordered four hard drives and a couple SSDs to populate all its slots; after placing the order, I did more research and realized it probably didn't include enough RAM (clearly they learned from Apple) and spent a little more money to order that, too. The hardware is great. Installing the drives, the SSDs, and the RAM was easy. But then I installed TrueNAS and things got messy.

UGREEN's hardware makes it pretty straightforward to replace their stock OS with something else, and my research had made it pretty clear that the best choice for all the stuff I wanted to do was going to be TrueNAS. I'm a little annoyed that TrueNAS isn't based on FreeBSD anymore, but none of the FreeBSD-based NAS options that are around seem like smart choices for a new installation right now (TrueNAS CORE is EOL and stuck on an old FreeBSD release; XigmaNAS seems to have just two developers who are working on it in spare time they don't have; zVault for now is just a debranded TrueNAS CORE, and thus on the same old FreeBSD release). Since the new Linux-based TrueNAS SCALE Community Edition is where the developer attention has gone and where most of the appliance-like features have migrated, that's where I went, too. And installing it was actually fine!

Until it wasn't.

Here is a recap of everything that went at least a little stupid if not a lot wrong over the course of installation, setup, and app deployment. Some of these things are like stepping on rakes; some are merely like stepping on stray construction toys in your bare feet.

1. In the 25.04.1 release, TrueNAS had a broken configuration of acme.sh for Let's Encrypt, making it impossible to request the certificate that the UI really wants you to have. As of when I set it up a fix had been committed to the next major release, but they hadn't yet ported it back to the current one. (25.04.2 is out now, presumably with this fix, but I haven't yet verified that it works). Pain rating: rake.

2. When setting up storage volumes, I set up the SSD before I set up the hard drives. I told it to use the SSD volume for its “System Dataset.” Then I configured the ZFS volume on the hard drives, and TrueNAS silently assigned its System Dataset to that volume instead of the SSD. This later caused one application setup to fail, which took a while to diagnose and fix. Pain rating: rake.

3. Related to the above item, whenever you install an app from the catalog the storage location for its data defaults to the System Dataset (labeled “ixVolume”). If the app has multiple storage locations (say, one for configuration, one for data storage), they'll all default to that. It's a dumb default. Usually this is just inconvenient, but two apps just flat out refused to launch with their storage located that way. If you find the right page in TrueNAS's documentation (see next item), you will, in fact, read that you should probably specify a different location for every app. If you should do that, why is ixVolume still the default? Pain rating: rake (once), construction toy (every other time).

4. I have a pet peeve about interfaces that rely on tooltips but which don't actually put helpful information in those tooltips. The application installation interface (used both for apps from the catalog and if you're installing a “custom” app as in item 7 below) is full of the wrong kind of tooltip, where the tooltip just repeats what the control's label says (e.g. the tooltip on the “Pull Policy” field says “The pull policy for the image.”) If there were a full documentation page somewhere that said how to use all the controls on that page to configure an app, it wouldn't be so bad, but see the next item.

5. The primary links to documentation from within the UI all seem to go to the documentation for the EOL Core release and not the current SCALE Community Edition release. And they changed their web strategy between releases, so if you think you can just get the current version by selecting the dropdown at the top of the page, you're in for a fun surprise when you're redirected to a useless landing page instead. And if you go to a search engine to find the right instructions, chances are you're going to find stuff about the next major release (25.10), which is in active development and is apparently getting new architecture for some of the interfaces. If you're still running 25.04, good luck to you. Pain rating: rake, because this is just a terrible self-own. It's way too hard to find complete documentation for the current release.

6. App installations sometimes result in incorrect permissions on the volumes those apps need. Some app installers have an option to fix permissions, but most of them don't. Pain rating: construction toy.

7. There are weird gaps in the app catalog. Officially you can just install Docker packages for apps that don't have catalog entries. There are even two different ways to install a docker package: a cryptic UI with unhelpful tooltips and no current documentation (item 4), or a spot you can paste in a YAML config. I guess the expectation is just that you know how to do that already or that somebody else has already documented it. Docker came along after I'd already sworn off Linux so it's a gap for me, and I lost a few hours trying to figure out a YAML config just for one app. Pain rating: rake, but one with a handle that only hits you in the thigh and not the face.

8. If you are going to have multiple apps that host services, you probably want the Nginx Proxy Manager app so you can get to all those services with reasonable URLs and not just ports. But Nginx Proxy Manager by default wants to own ports 80 and 443, which the TrueNAS UI also wants to own. The installation will fail unless you reassign the ports TrueNAS uses before you install the NPM app, but this isn't documented anywhere. There are forum posts about it, though. There's also a checkbox in the TrueNAS UI about redirecting traffic from 80 to 443, but it's incompatible with Nginx Proxy Manager. I see now they've changed the language on the tooltip a little, so maybe it's less broken in 25.04.2. Pain rating: like stepping on a construction toy, then stepping on more of them as you try to get away from the first one.

9. There were a couple Linux services that were enabled by default that failed on startup because they weren't configured. I looked into both of them, realized I didn't need either one (at least one was related to directory-based user authentication I won't be using), and disabled them. Pain rating: construction toy. If I hadn't been looking at startup logs while I was setting everything up I might not have known these unnecessary services were failing.

I also encountered some issues that I can't solely blame on TrueNAS and/or Linux, like an issue with music files I exported from Apple's “Music” app (still iTunes to me) if they had unicode combining characters in their filenames (think ñ or à). Turns out Apple handles that one way, but to get those files into playlists in Navidrome I had to “precompose” the playlist files. But that's not as bad as the whole week I spent on a photo export, writing code in a language I only barely know how to use (Python) to automate uploads directly from the Photos app on a Mac to my Immich server. (It's pretty spiffy, though. It creates albums if they don't exist and stacks the edited/original/raw versions of every image that has more than one).

I'm basically done with setup now and the thing that cost me the most time was working around Apple software, so most of these complaints are just complaints. But it would be nice not to have complaints at all.