In today’s digital world, our lives—both personal and professional—are recorded as data. From family photos to crucial company databases, losing this information can be catastrophic. Despite this, many individuals and businesses still treat backups as an afterthought. Here is a complete guide to building a powerful, automated, and secure backup system using free tools: UrBackup, TrueNAS Scale, and Tailscale.
Why You Need a Plan B: The Importance of Backups
Imagine one morning your laptop’s hard drive refuses to work. Or the server that runs your business falls victim to a ransomware attack, and all your files are encrypted. These aren’t scenarios from science-fiction films but everyday reality. Hardware failure, human error, malicious software, or even theft—the threats are numerous.
A backup is your insurance policy. It’s the only way to quickly and painlessly recover valuable data in the event of a disaster, minimising downtime and financial loss. Without it, rebuilding lost information is often impossible or astronomically expensive.
The Golden Rule: The 3-2-1 Strategy
In the world of data security, there is a simple but incredibly effective principle known as the 3-2-1 strategy. It states that you should have:
THREE copies of your data (the original and two backups).
On TWO different storage media (e.g., a disk in your computer and a disk in a NAS server).
ONE copy in a different location (off-site), in case of fire, flood, or theft at your main location.
Having three copies of your data drastically reduces the risk of losing them all simultaneously. If one drive fails, you have a second. If the entire office is destroyed, you have a copy in the cloud or at home.
A Common Misconception: Why RAID is NOT a Backup
Many NAS server users mistakenly believe that a RAID configuration absolves them of the responsibility to make backups. This is a dangerous error.
RAID (Redundant Array of Independent Disks) is a technology that provides redundancy and high availability, not data security. It protects against the physical failure of a hard drive. Depending on the configuration (e.g., RAID 1, RAID 5, RAID 6, or their RAID-Z equivalents in TrueNAS), the array can survive the failure of one or even two drives at the same time, allowing them to be replaced without data loss or system downtime.
However, RAID will not protect you from:
Human error: Accidentally deleting a file is instantly replicated across all drives in the array.
Ransomware attack: Encrypted files are immediately synchronised across all drives.
Power failure or RAID controller failure: This can lead to the corruption of the entire array.
Theft or natural disaster: Losing the entire device means losing all the data.
Remember: Redundancy protects against hardware failure; a backup protects against data loss.
Your Backup Hub: UrBackup on TrueNAS Scale
Creating a robust backup system doesn’t have to involve expensive subscriptions. An ideal solution is to combine the TrueNAS Scale operating system with the UrBackup application.
TrueNAS Scale: A powerful, free operating system for building NAS servers. It is based on Linux and offers advanced features such as the ZFS file system and support for containerised applications.
UrBackup: An open-source, client-server software for creating backups. It is extremely efficient and flexible, allowing for the backup of both individual files and entire disk images.
The TrueNAS Protective Shield: ZFS Snapshots
One of the most powerful features of TrueNAS, resulting from its use of the ZFS file system, is snapshots. A snapshot is an instantly created, read-only image of the entire file system at a specific moment. It works like freezing your data in time.
Why is this so important in the context of ransomware?
When ransomware attacks and encrypts files on a network share, these changes affect the “live” version of the data. However, previously taken snapshots remain untouched and unchanged because they are inherently read-only. In the event of an attack, you can restore the entire dataset to its pre-infection state in seconds, completely nullifying the effects of the attack.
You can configure TrueNAS to automatically create snapshots (e.g., every hour) and retain them for a specified period. This creates an additional, incredibly powerful layer of protection that perfectly complements the backups performed by UrBackup.
Advantages and Disadvantages of the Solution
Advantages:
Full control and privacy: Your data is stored on your own hardware.
No licence fees: The software is completely free.
Exceptional efficiency: Incremental backups save space and time.
Flexibility: Supports Windows, macOS, Linux, physical servers, and VPS.
Disk image backups: Ability to perform a “bare-metal restore” of an entire system.
Disadvantages:
Requires your own hardware: You need to have a NAS server.
Initial configuration: Requires some technical knowledge.
Full responsibility: The user is responsible for the security and operation of the server.
Step-by-Step: Installation and Configuration
1. Installing UrBackup on TrueNAS Scale
Log in to the TrueNAS web interface.
Navigate to the Apps section.
Search for the UrBackup application and click Install.
In the most important configuration step, you must specify the path where backups will be stored (e.g., /mnt/YourPool/backups).
After the installation is complete, start the application and go to its web interface.
2. Basic Server Configuration
In the UrBackup interface, go to Settings. The most important initial options are:
Path to backup storage: This should already be set during installation.
Backup intervals: Set how often incremental backups (e.g., every few hours) and full backups (e.g., every few weeks) should be performed.
Email settings: Configure email notifications to receive reports on the status of your backups.
3. Installing the Client on Computers
The process of adding a computer to the backup system consists of two stages: registering it on the server and installing the software on the client machine.
a) Adding a new client on the server:
In the UrBackup interface, go to the Status tab.
Click the blue + Add new client button.
Select the option Add new internet/active client. This is recommended as it works both on the local network and over the internet (e.g., via Tailscale).
Enter a unique name for the new client (e.g., “Annas-Laptop” or “Web-Server”) and click Add client.
b) Installing the software on the client machine:
After adding the client on the server, while still on the Status tab, you will see buttons to Download client for Windows and Download client for Linux.
Click the appropriate button and select the name of the client you just added from the drop-down list.
Download the prepared installation file (.exe or .sh). It is already fully configured to connect to your server.
Run the installer on the client computer and follow the instructions.
After a few minutes, the new client should connect to the server and appear on the list with an “Online” status, ready for its first backup.
Security Above All: Tailscale Enters the Scene
How can you securely back up computers located outside your local network? The ideal solution is Tailscale. It creates a secure, private network (a mesh VPN) between all your devices, regardless of their location.
Why use Tailscale with UrBackup?
Simplicity: Installation and configuration take minutes.
“Zero Trust” Security: Every connection is end-to-end encrypted.
Stable IP Addresses: Each device receives a static IP address from the 100.x.x.x range, which does not change even when the device moves to a different physical location.
What to do if the IP address changes?
If for some reason you need to change the IP address of the UrBackup server (e.g., after switching from another VPN to Tailscale), the procedure is simple:
Update the address on the UrBackup server: In Settings -> Internet/Active Clients, enter the new, correct server address (e.g., urbackup://100.x.x.x).
Download the updated installer: On the Status tab, click Download client, select the offline client from the list, and download a new installation script for it.
Run the installer on the client: Running the new installer will automatically update the configuration on the client machine.
Managing and Monitoring Backups
The UrBackup interface provides all the necessary tools to supervise the system.
Status: The main dashboard showing a list of all clients, their online/offline status, and the status of their last backup.
Activities: A live view of currently running operations, such as file indexing or data transfer.
Backups: A list of all completed backups for each client, with the ability to browse and restore files.
Logs: A detailed record of all events, errors, and warnings—an invaluable tool for diagnosing problems.
Statistics: Charts and tables showing disk space usage by individual clients over time.
Backing Up Databases: Do It Right!
Never back up a database by simply copying its files from the disk while the service is running! This risks creating an inconsistent copy that will be useless. The correct method is to perform a “dump” using tools like mysqldump or mariadb-dump.
Method 2: Each Database to a Separate File (Recommended)
A more flexible solution. The script below will automatically save each database to a separate, compressed file. It should be run periodically (e.g., via cron) just before the scheduled backup by UrBackup.
#!/bin/bash
# Configuration
BACKUP_DIR="/var/backups/mysql"
DB_USER="root"
DB_PASS="YourSuperSecretPassword"
# Check if user and password are provided
if [ -z "$DB_USER" ] || [ -z "$DB_PASS" ]; then
echo "Error: DB_USER or DB_PASS variables are not set in the script."
exit 1
fi
# Create backup directory if it doesn't exist
mkdir -p "$BACKUP_DIR"
# Get a list of all databases, excluding system databases
DATABASES=$(mysql -u "$DB_USER" -p"$DB_PASS" -e "SHOW DATABASES;" | tr -d " " | grep -vE "(Database|information_schema|performance_schema|mysql|sys)")
# Loop through each database
for db in $DATABASES; do
echo "Dumping database: $db"
# Perform the dump and compress on the fly
mysqldump -u "$DB_USER" -p"$DB_PASS" --databases "$db" | gzip > "$BACKUP_DIR/$db-$(date +%Y-%m-%d).sql.gz"
if [ $? -eq 0 ]; then
echo "Dump of database $db completed successfully."
else
echo "Error during dump of database $db."
fi
done
# Optional: Remove old backups (older than 7 days)
find "$BACKUP_DIR" -type f -name "*.sql.gz" -mtime +7 -exec rm {} \;
echo "Backup process for all databases has finished."
Your Digital Fortress
Having a solid, automated backup strategy is not a luxury but an absolute necessity. Combining the power of TrueNAS Scale with its ZFS snapshots, the flexibility of UrBackup, and the security of Tailscale allows you to build a multi-layered, enterprise-class defence system at zero software cost.
It is an investment of time that provides priceless peace of mind. Remember, however, that no system is entirely maintenance-free. Regularly monitoring logs, checking email reports, and, most importantly, periodically performing test restores of your files are the final, crucial elements that turn a good backup system into an impregnable fortress protecting your most valuable asset—your data.
The modern internet is a battlefield for our attention, and adverts have become the primary ammunition. This is felt particularly acutely on smartphones, where intrusive banners and pop-up windows can effectively discourage you from browsing content. However, there is an effective and comprehensive solution that allows you to create your own protective shield, not only on your home network but on any device, wherever you are.
The Problem: Digital Clutter and Loss of Privacy
Anyone who has tried to read an article on a smartphone is familiar with this scenario: the content is regularly interrupted by adverts that take up a significant portion of the screen, slow down the page’s loading time, and consume precious mobile data. While this problem is irritating on desktop computers, on smaller screens it becomes a serious barrier to accessing information.
Traditional browser plug-ins solve the problem only partially and on a single device. They don’t protect us in mobile apps, on Smart TVs, or on games consoles. What’s worse, ubiquitous tracking scripts collect data about our activity, creating detailed marketing profiles.
The Solution: Centralised Management with AdGuard Home
The answer is AdGuard Home—software that acts as a DNS server, filtering traffic at a network-wide level. By installing it on a home server, such as the popular TrueNAS, we gain a central point of control over all devices connected to our network.
Installation and configuration of AdGuard Home on TrueNAS are straightforward thanks to its Apps system. A key step during installation is to tick the “Host Network” option. This allows AdGuard Home to see the real IP addresses of the devices on your network, enabling precise monitoring and management of clients in the admin panel. Without this option, all queries would appear to originate from the server’s single IP address.
After installation, the crucial step is to direct DNS queries from all devices to the address of our AdGuard server. This can be achieved in several ways, but thanks to Tailscale, the process becomes incredibly simple.
Traditional Methods vs. The Tailscale Approach
In a conventional approach, to direct traffic to AdGuard Home, we would need to change the DNS addresses in our router’s settings. When this isn’t possible (which is often the case with equipment from an internet service provider), the alternative is to configure AdGuard Home as a DHCP server, which will automatically assign the correct DNS address to devices (this requires disabling the DHCP server on the router). The last resort is to change the DNS manually on every device in the house. It must be stressed, however, that all these methods work only within the local network and are completely ineffective for mobile devices using cellular data away from home.
However, if we plan to use Tailscale for protection outside the home, we can also use it to configure the local network. This is an incredibly elegant solution: if we install the Tailscale client on all our devices (computers, phones) and set our AdGuard server’s DNS address in its admin panel, enabling the “Override local DNS” option, we don’t need to make any changes to the router or manually on individual devices. Tailscale will automatically force every device in our virtual network to use AdGuard, regardless of which physical network it is connected to.
AdGuard Home Features: Much More Than Ad Blocking
Protection against Malware: Automatically blocks access to sites known for phishing, malware, and scams.
Parental Controls: Allows you to block sites with adult content, an invaluable feature in homes with children.
Filter Customisation: We can use ready-made, regularly updated filter lists or add our own rules.
Detailed Statistics: The panel shows which queries are being blocked, which devices are most active, and which domains are generating the most traffic.
For advanced users, the ability to manage clients is particularly useful. Each device on the network can be given a friendly name (e.g., “Anna-Laptop,” “Tom-Phone”) and assigned individual filtering rules. In my case, for VPS servers that do not require ad blocking, I have set default DNS servers (e.g., 1.1.1.1 and 8.8.8.8), so their traffic is ignored by the AdGuard filters.
The Challenge: Blocking Adverts Beyond the Home Network
While protection on the local network is already a powerful tool, true freedom from adverts comes when we can use it away from home. By default, when a smartphone connects to a mobile network, it loses contact with the home AdGuard server. Attempting to expose a DNS server to the public internet by forwarding ports on your router is not only dangerous but also ineffective. Most mobile operating systems, like Android and iOS, do not allow changing the DNS server for mobile connections, making such a solution impossible. This is where Tailscale comes to the rescue.
Tailscale: Your Private Network, Anywhere
Tailscale is a service based on the WireGuard protocol that creates a secure, virtual private network (a “Tailnet”) between your devices. Regardless of where they are, computers, servers, and phones can communicate with each other as if they were on the same local network.
Installing Tailscale on TrueNAS and on mobile devices is swift and straightforward. After logging in with the same account, all devices see each other in the Tailscale admin panel. To combine the power of both tools, you need to follow these key steps:
In the Tailscale admin panel, under the DNS tab, enable the Override local DNS option.
As the global DNS server, enter the IP address of our TrueNAS server within the Tailnet (e.g., 100.x.x.x).
With this configuration, all DNS traffic from our phone, even when it’s using a 5G network on the other side of the country, is sent through a secure tunnel to the Tailscale server on TrueNAS and then processed by AdGuard Home. The result? Adverts, trackers, and malicious sites are blocked on your phone, anytime and anywhere.
Advanced Tailscale Features: Subnet Routes and Exit Node
Tailscale offers two powerful features that further extend the capabilities of our network:
Subnet routes: This allows you to share your entire home LAN (e.g., 192.168.1.0/24) with devices on your Tailnet. After configuring your TrueNAS server as a “subnet router,” your phone, while away from home, can access not only the server itself but also your printer, IP camera, or other devices on the local network, just as if you were at home.
Exit node: This feature turns your home server into a fully-fledged VPN server. Once activated, all internet traffic from your Tailnet (not just DNS queries) is tunnelled through your home internet connection. This is the perfect solution when using untrusted public Wi-Fi networks (e.g., in a hotel or at an airport), as all your traffic is encrypted and protected. If your home server is in the UK, you also gain a UK IP address while abroad.
Checking the Effectiveness of Ad Blocking
To find out how effective your ad-blocking filters are, you can visit https://adblock.turtlecute.org/. There, you will see what types of adverts are being blocked and which are still being displayed. This will help you to fine-tune your filter lists in AdGuard Home.
Summary: Advantages and Disadvantages
Creating such a system is an investment of time, but the benefits are invaluable.
Advantages:
Complete and Unified Protection: Blocks adverts and threats on all devices, on any network, with minimal configuration.
Centralised Management: A single place to configure rules for the entire household.
Increased Privacy and Security: Reduces tracking and encrypts traffic on public networks.
Performance: Faster page loading and lower mobile data consumption.
Disadvantages:
Requires a Server: Needs a 24/7 device like a TrueNAS server to be running.
Dependency on Home Connection: The speed of DNS responses and bandwidth (in Exit Node mode) outside the home depends on your internet’s upload speed.
The combination of AdGuard Home and Tailscale is a powerful tool for anyone who values a clean, fast, and secure internet. It is a declaration of digital independence that places control back into the hands of the user, away from advertising corporations.
In today’s digital world, where remote work and distributed infrastructure are becoming the norm, secure access to network resources is not so much a luxury as an absolute necessity. Virtual Private Networks (VPNs) have long been the answer to these needs, yet traditional solutions can be complicated and slow. Enter WireGuard—a modern VPN protocol that is revolutionising the way we think about secure tunnels. Combined with the power of the TrueNAS Scale system and the simplicity of the WG-Easy application, we can create an exceptionally efficient and easy-to-manage solution.
This article is a comprehensive guide that will walk you through the process of configuring a secure WireGuard VPN tunnel step by step. We will connect a TrueNAS Scale server, running on your home or company network, with a fleet of public VPS servers. Our goal is to create intelligent “split-tunnel” communication, ensuring that only necessary traffic is routed through the VPN, thereby maintaining maximum internet connection performance.
What Is WireGuard and Why Is It a Game-Changer?
Before we delve into the technical configuration, it’s worth understanding why WireGuard is gaining such immense popularity. Designed from the ground up with simplicity and performance in mind, it represents a breath of fresh air compared to older, more cumbersome protocols like OpenVPN or IPsec.
The main advantages of WireGuard include:
Minimalism and Simplicity: The WireGuard source code consists of just a few thousand lines, in contrast to the hundreds of thousands for its competitors. This not only facilitates security audits but also significantly reduces the potential attack surface.
Unmatched Performance: By operating at the kernel level of the operating system and utilising modern cryptography, WireGuard offers significantly higher transfer speeds and lower latency. In practice, this means smoother access to files and services.
Modern Cryptography: WireGuard uses the latest, proven cryptographic algorithms such as ChaCha20, Poly1305, Curve25519, BLAKE2s, and SipHash24, ensuring the highest level of security.
Ease of Configuration: The model, based on the exchange of public keys similar to SSH, is far more intuitive than the complicated certificate management found in other VPN systems.
The Power of TrueNAS Scale and the Convenience of WG-Easy
TrueNAS Scale is a modern, free operating system for building network-attached storage (NAS) servers, based on the solid foundations of Linux. Its greatest advantage is its support for containerised applications (Docker/Kubernetes), which allows for easy expansion of its functionality. Running a WireGuard server directly on a device that is already operating 24/7 and storing our data is an extremely energy- and cost-effective solution.
This is where the WG-Easy application comes in—a graphical user interface that transforms the process of managing a WireGuard server from editing configuration files in a terminal to simple clicks in a web browser. Thanks to WG-Easy, we can create profiles for new devices in moments, generate their configurations, and monitor the status of connections.
Step 1: Designing the Network Architecture – The Foundation of Stability
Before we launch any software, we must create a solid plan. Correctly designing the topology and IP addressing is the key to a stable and secure solution.
The “Hub-and-Spoke” Model: Your Command Centre
Our network will operate based on a “hub-and-spoke” model.
Hub: The central point (server) of our network will be TrueNAS Scale. All other devices will connect to it.
Spokes: Our VPS servers will be the clients (peers), or the “spokes” connected to the central hub.
In this model, all communication flows through the TrueNAS server by default. This means that for one VPS to communicate with another, the traffic must pass through the central hub.
To avoid chaos, we will create a dedicated subnet for our virtual network. In this guide, we will use 10.8.0.0/24.
Device Role
Host Identifier
VPN IP Address
Server (Hub)
TrueNAS-Scale
10.8.0.1
Client 1 (Spoke)
VPS1
10.8.0.2
Client 2 (Spoke)
VPS2
10.8.0.3
Client 3 (Spoke)
VPS3
10.8.0.4
The Fundamental Rule: One Client, One Identity
A tempting thought arises: is it possible to create a single configuration file for all VPS servers? Absolutely not. This would be a breach of a fundamental WireGuard security principle. Identity in this network is not based on a username and password, but on a unique pair of cryptographic keys. Using the same configuration on multiple machines is like giving the same house key to many different people—the server would be unable to distinguish between them, which would lead to routing chaos and a security breakdown.
Step 2: Prerequisite – Opening the Gateway to the World
The most common pitfall when configuring a home server is forgetting about the router. Your TrueNAS server is on a local area network (LAN) and has a private IP address (e.g., 192.168.0.13), which makes it invisible from the internet. For the VPS servers to connect to it, you must configure port forwarding on your router.
You need to create a rule that directs packets arriving from the internet on a specific port straight to your TrueNAS server.
Protocol: UDP (WireGuard uses UDP exclusively)
External Port: 51820 (the standard WireGuard port)
Internal IP Address: The IP address of your TrueNAS server on the LAN
Internal Port: 51820
Without this rule, your VPN server will never work.
Step 3: Hub Configuration – Launching the Server on TrueNAS
Launch the WG-Easy application on your TrueNAS server. The configuration process boils down to creating a separate profile for each client (each VPS server).
Click “New” and fill in the form for the first VPS, paying special attention to the fields below:
Field Name in WG-Easy
Example Value (for VPS1)
Explanation
Name
VPS1-Public
A readable label to help you identify the client.
IPv4 Address
10.8.0.2
A unique IP address for this VPS within the VPN, according to our plan.
Allowed IPs
192.168.0.0/24, 10.8.0.0/24
This is the heart of the “split-tunnel” configuration. It tells the client (VPS) that only traffic to your local network (LAN) and to other devices on the VPN should be sent through the tunnel. All other traffic (e.g., to Google) will take the standard route.
Server Allowed IPs
10.8.0.2/32
A critical security setting. It informs the TrueNAS server to only accept packets from this specific client from its assigned IP address. The /32 mask prevents IP spoofing.
Persistent Keepalive
25
An instruction for the client to send a small “keep-alive” packet every 25 seconds. This is necessary to prevent the connection from being terminated by routers and firewalls along the way.
After filling in the fields, save the configuration. Repeat this process for each subsequent VPS server, remembering to assign them consecutive IP addresses (10.8.0.3, 10.8.0.4, etc.).
Once you save the profile, WG-Easy will generate a .conf configuration file for you. Treat this file like a password—it contains the client’s private key! Download it and prepare to upload it to the VPS server.
Step 4: Spoke Configuration – Activating Clients on the VPS Servers
Now it’s time to bring our “spokes” to life. Assuming your VPS servers are running Linux (e.g., Debian/Ubuntu), the process is very straightforward.
Upload and secure the configuration file: Copy the previously downloaded wg0.conf file to the /etc/wireguard/ directory on the VPS server. Then, change its permissions so that only the administrator can read it: # On the VPS server: sudo mv /path/to/your/wg0.conf /etc/wireguard/wg0.conf sudo chmod 600 /etc/wireguard/wg0.conf
Start the tunnel: Use a simple command to activate the connection. The interface name (wg0) is derived from the configuration file name. sudo wg-quick up wg0
Ensure automatic start-up: To have the VPN tunnel start automatically after every server reboot, enable the corresponding system service: sudo systemctl enable wg-quick@wg0.service
Repeat these steps on each VPS server, using the unique configuration file generated for each one.
Step 5: Verification and Diagnostics – Checking if Everything Works
After completing the configuration, it’s time for the final test.
Checking the Connection Status
On both the TrueNAS server and each VPS, execute the command:
sudo wg show
Look for two key pieces of information in the output:
latest handshake: This should show a recent time (e.g., “a few seconds ago”). This is proof that the client and server have successfully connected.
transfer: received and sent values greater than zero indicate that data is actually flowing through the tunnel.
The Final Test: Validating the “Split-Tunnel”
This is the test that will confirm we have achieved our main goal. Log in to one of the VPS servers and perform the following tests:
Test connectivity within the VPN: Try to ping the TrueNAS server using its VPN and LAN addresses. ping 10.8.0.1 # VPN address of the TrueNAS server ping 192.168.0.13 # LAN address of the TrueNAS server (use your own)
If you receive replies, it means that traffic to your local network is being correctly routed through the tunnel.
Test the path to the internet: Use the traceroute tool to check the route packets take to a public website. traceroute google.com
The result of this command is crucial. The first “hop” on the route must be the default gateway address of your VPS hosting provider, not the address of your VPN server (10.8.0.1). If this is the case—congratulations! Your “split-tunnel” configuration is working perfectly.
Troubleshooting Common Problems
No “handshake”: The most common cause is a connection issue. Double-check the UDP port 51820 forwarding configuration on your router, as well as any firewalls in the path (on TrueNAS, on the VPS, and in your cloud provider’s panel).
There is a “handshake”, but ping doesn’t work: The problem usually lies in the Allowed IPs configuration. Ensure the server has the correct client VPN address entered (e.g., 10.8.0.2/32), and the client has the networks it’s trying to reach in its configuration (e.g., 192.168.0.0/24).
All traffic is going through the VPN (full-tunnel): This means that in the client’s configuration file, under the [Peer] section, the Allowed IPs field is set to 0.0.0.0/0. Correct this setting in the WG-Easy interface, download the new configuration file, and update it on the client.
Creating your own secure and efficient VPN server based on TrueNAS Scale and WireGuard is well within reach. It is a powerful solution that not only enhances security but also gives you complete control over your network infrastructure.
Section 1: Introduction: Simplifying Home Lab Access with Nginx Proxy Manager on TrueNAS Scale
Modern home labs have evolved from simple setups into complex ecosystems running dozens of services, from media servers like Plex or Jellyfin, to home automation systems such as Home Assistant, to personal clouds and password managers. Managing access to each of these services, each operating on a unique combination of an IP address and port number, quickly becomes impractical, inconvenient, and, most importantly, insecure. Exposing multiple ports to the outside world increases the attack surface and complicates maintaining a consistent security policy.
The solution to this problem, employed for years in corporate environments, is the implementation of a central gateway or a single point of entry for all incoming traffic. In networking terminology, this role is fulfilled by a reverse proxy. This is an intermediary server that receives all requests from clients and then, based on the domain name, directs them to the appropriate service running on the internal network. Such an architecture not only simplifies access, allowing the use of easy-to-remember addresses (e.g., jellyfin.mydomain.co.uk instead of 192.168.1.50:8096), but also forms a key component of a security strategy.
In this context, two technologies are gaining particular popularity among enthusiasts: TrueNAS Scale and Nginx Proxy Manager. TrueNAS Scale, based on the Debian Linux system, has transformed the traditional NAS (Network Attached Storage) device into a powerful, hyper-converged infrastructure (HCI) platform, capable of natively running containerised applications and virtual machines. In turn, Nginx Proxy Manager (NPM) is a tool that democratises reverse proxy technology. It provides a user-friendly, graphical interface for the powerful but complex-to-configure Nginx server, making advanced features, such as automatic SSL certificate management, accessible without needing to edit configuration files from the command line.
This article provides a comprehensive overview of the process of deploying Nginx Proxy Manager on the TrueNAS Scale platform. The aim is not only to present “how-to” instructions but, above all, to explain why each step is necessary. The analysis will begin with an in-depth discussion of both technologies and their interactions. Then, a detailed installation process will be carried out, considering platform-specific challenges and their solutions, including the well-known issue of the application getting stuck in the “Deploying” state. Subsequently, using the practical example of a Jellyfin media server, the configuration of a proxy host will be demonstrated, along with advanced security options. The report will conclude with a summary of the benefits and suggest further steps to fully leverage the potential of this powerful duo.
Section 2: Tool Analysis: Nginx Proxy Manager and the TrueNAS Scale Application Ecosystem
Understanding the fundamental principles of how Nginx Proxy Manager works and the architecture in which it is deployed—the TrueNAS Scale application system—is crucial for successful installation, effective configuration, and, most importantly, efficient troubleshooting. These two components, though designed to work together, each have their own unique characteristics, the ignorance of which is the most common cause of failure.
At the core of NPM’s functionality lies the concept of a reverse proxy, which is fundamental to modern network architecture. Understanding how it works allows one to appreciate the value that NPM brings.
Definition and Functions of a Reverse Proxy
A reverse proxy is a server that acts as an intermediary on the server side. Unlike a traditional (forward) proxy, which acts on behalf of the client, a reverse proxy acts on behalf of the server (or a group of servers). It receives requests from clients on the internet and forwards them to the appropriate servers on the local network that actually store the content. To an external client, the reverse proxy is the only visible point of contact; the internal network structure remains hidden.
The key benefits of this solution are:
Security: Hiding the internal network topology and the actual IP addresses of application servers significantly hinders direct attacks on these services.
Centralised SSL/TLS Management (SSL Termination): Instead of configuring SSL certificates on each of a dozen application servers, you can manage them in one place—on the reverse proxy. Traffic encryption and decryption (SSL Termination) occurs at the proxy server, which offloads the backend servers.
Load Balancing: In more advanced scenarios, a reverse proxy can distribute traffic among multiple identical application servers, ensuring high availability and service scalability.
Simplified Access: It allows access to multiple services through standard ports 80 (HTTP) and 443 (HTTPS) using different subdomains, eliminating the need to remember and open multiple ports.
NPM as a Management Layer
It should be emphasised that Nginx Proxy Manager is not a new web server competing with Nginx. It is a management application, built on the open-source Nginx, which serves as a graphical user interface (GUI) for its reverse proxy functions. Instead of manually editing complex Nginx configuration files, the user can perform the same operations with a few clicks in an intuitive web interface.
The main features that have contributed to NPM’s popularity are:
Graphical User Interface: Based on the Tabler framework, the interface is clear and easy to use, which drastically lowers the entry barrier for users who are not Nginx experts.
SSL Automation: Built-in integration with Let’s Encrypt allows for the automatic, free generation of SSL certificates and their periodic renewal. This is one of the most important and appreciated features.
Docker-based Deployment: NPM is distributed as a ready-to-use Docker image, which makes its installation on any platform that supports containers extremely simple.
Access Management: The tool offers features for creating Access Control Lists (ACLs) and managing users with different permission levels, allowing for granular control over access to individual services.
Comparison: NPM vs. Traditional Nginx
The choice between Nginx Proxy Manager and manual Nginx configuration is a classic trade-off between simplicity and flexibility. The table below outlines the key differences between these two approaches.
Aspect
Nginx Proxy Manager
Traditional Nginx
Management Interface
Graphical User Interface (GUI) simplifying configuration.
Command Line Interface (CLI) and editing text files; requires technical knowledge.
SSL Configuration
Fully automated generation and renewal of Let’s Encrypt certificates.
Manual configuration using tools like Certbot; greater control.
Learning Curve
Low; ideal for beginners and hobbyists.
Steep; requires understanding of Nginx directives and web server architecture.
Flexibility
Limited to features available in the GUI; advanced rules can be difficult to implement.
Full flexibility and the ability to create highly customised, complex configurations.
Scalability / Target User
Ideal for home labs, small to medium deployments. Hobbyist, small business owner, home lab user.
A better choice for large-scale, high-load corporate environments. Systems administrator, DevOps engineer, developer.
This table clearly shows that NPM is a tool strategically tailored to the needs of its target audience—home lab enthusiasts. These users consciously sacrifice some advanced flexibility for the significant benefits of ease of use and speed of deployment.
Subsection 2.2: Application Architecture in TrueNAS Scale
To understand why installing NPM on TrueNAS Scale can encounter specific problems, it is necessary to know how this platform manages applications. It is not a typical Docker environment.
Foundations: Linux and Hyper-convergence
A key architectural change in TrueNAS Scale compared to its predecessor, TrueNAS CORE, was the switch from the FreeBSD operating system to Debian, a Linux distribution. This decision opened the door to native support for technologies that have dominated the cloud and containerisation world, primarily Docker containers and KVM-based virtualisation. As a result, TrueNAS Scale became a hyper-converged platform, combining storage, computing, and virtualisation functions.
The Application System
Applications are distributed through Catalogs, which function as repositories. These catalogs are further divided into so-called “trains,” which define the stability and source of the applications:
stable: The default train for official, iXsystems-tested applications.
enterprise: Applications verified for business use.
community: Applications created and maintained by the community. This is where Nginx Proxy Manager is located by default.
test: Applications in the development phase.
NPM’s inclusion in the community catalog means that while it is easily accessible, its technical support relies on the community, not directly on the manufacturer of TrueNAS.
Storage Management for Applications
Before any application can be installed, TrueNAS Scale requires the user to specify a ZFS pool that will be dedicated to storing application data. When an application is installed, its data (configuration, databases, etc.) must be saved somewhere persistently. TrueNAS Scale offers several options here, but the default and recommended for simplicity is ixVolume.
ixVolume is a special type of volume that automatically creates a dedicated, system-managed ZFS dataset within the selected application pool. This dataset is isolated, and the system assigns it very specific permissions. By default, the owner of this dataset becomes the system user apps with a user ID (UID) of 568 and a group ID (GID) of 568. The running application container also operates with the permissions of this very user.
This is the crux of the problem. The standard Docker image for Nginx Proxy Manager contains startup scripts (e.g., those from Certbot, the certificate handling tool) that, on first run, attempt to change the owner (chown) of data directories, such as /data or /etc/letsencrypt, to ensure they have the correct permissions. When the NPM container starts within the sandboxed TrueNAS application environment, its startup script, running as the unprivileged apps user (UID 568), tries to execute the chown operation on the ixVolume. This operation fails because the apps user is not the owner of the parent directories and does not have permission to change the owner of files on a volume managed by K3s. This permission error causes the container’s startup script to halt, and the container itself never reaches the “running” state, which manifests in the TrueNAS Scale interface as an endless “Deploying” status.
Section 3: Installing and Configuring Nginx Proxy Manager on TrueNAS Scale
The process of installing Nginx Proxy Manager on TrueNAS Scale is straightforward, provided that attention is paid to a few key configuration parameters that are often a source of problems. The following step-by-step instructions will guide you through this process, highlighting the critical decisions that need to be made.
Step 1: Preparing TrueNAS Scale
Before proceeding with the installation of any application, you must ensure that the application service in TrueNAS Scale is configured correctly.
Log in to the TrueNAS Scale web interface.
Navigate to the Apps section.
If the service is not yet configured, the system will prompt you to select a ZFS pool to be used for storing all application data. Select the appropriate pool and save the settings. After a moment, the service status should change to “Running”.
Step 2: Finding the Application
Nginx Proxy Manager is available in the official community catalog.
In the Apps section, go to the Discover tab.
In the search box, type nginx-proxy-manager.
The application should appear in the results. Ensure it comes from the community catalog.
Click the Install button to proceed to the configuration screen.
Step 3: Key Configuration Parameters
The installation screen presents many options. Most of them can be left with their default values, but a few sections require special attention.
Application Name
In the Application Name field, enter a name for the installation, for example, nginx-proxy-manager. This name will be used to identify the application in the system.
Network Configuration
This is the most important and most problematic stage of the configuration. By default, the TrueNAS Scale management interface uses the standard web ports: 80 for HTTP and 443 for HTTPS. Since Nginx Proxy Manager, to act as a gateway for all web traffic, should also listen on these ports, a direct conflict arises. There are two main strategies to solve this problem, each with its own set of trade-offs.
Strategy A (Recommended): Change TrueNAS Scale Ports This method is considered the “cleanest” from NPM’s perspective because it allows it to operate as it was designed.
Cancel the NPM installation and go to System Settings -> General. In the GUI SSL/TLS Certificate section, change the Web Interface HTTP Port to a custom one, e.g., 880, and the Web Interface HTTPS Port to, e.g., 8443.
Save the changes. From this point on, access to the TrueNAS Scale interface will be available at http://<truenas-ip-address>:880 or https://<truenas-ip-address>:8443.
Return to the NPM installation and in the Network Configuration section, assign the HTTP Port to 80 and the HTTPS Port to 443.
Advantages: NPM runs on standard ports, which simplifies configuration and eliminates the need for port translation on the router.
Disadvantages: It changes the fundamental way of accessing the NAS itself. In rare cases, as noted on forums, this can cause unforeseen side effects, such as problems with SSH connections between TrueNAS systems.
Strategy B (Alternative): Use High Ports for NPM This method is less invasive to the TrueNAS configuration itself but shifts the complexity to the router level.
In the NPM configuration, under the Network Configuration section, leave the TrueNAS ports unchanged and assign high, unused ports to NPM, e.g., 30080 for HTTP and 30443 for HTTPS. TrueNAS Scale reserves ports below 9000 for the system, so you should choose values above this threshold.
After installing NPM, configure port forwarding on your edge router so that incoming internet traffic on port 80 is directed to port 30080 of the TrueNAS IP address, and traffic from port 443 is directed to port 30443.
Advantages: The TrueNAS Scale configuration remains untouched.
Disadvantages: Requires additional configuration on the router. Each proxied service will require explicit forwarding, which can be confusing.
The ideal solution would be to assign a dedicated IP address on the local network to NPM (e.g., using macvlan technology), which would completely eliminate the port conflict. Unfortunately, the graphical interface of the application installer in TrueNAS Scale does not provide this option in a simple way.
Storage Configuration
To ensure that the NPM configuration, including created proxy hosts and SSL certificates, survives updates or application redeployments, you must configure persistent storage.
In the Storage Configuration section, configure two volumes.
For Nginx Proxy Manager Data Storage (path /data) and Nginx Proxy Manager Certs Storage (path /etc/letsencrypt), select the ixVolume type.
Leaving these settings will ensure that TrueNAS creates dedicated ZFS datasets for the configuration and certificates, which will be independent of the application container itself.
Step 4: First Run and Securing the Application
After configuring the above parameters (and possibly applying the fixes from Section 4), click Install. After a few moments, the application should transition to the “Running” state.
Access to the NPM interface is available at http://<truenas-ip-address>:PORT, where PORT is the WebUI port configured during installation (defaults to 81 inside the container but is mapped to a higher port, e.g., 30020, if the TrueNAS ports were not changed).
The default login credentials are:
Email: admin@example.com
Password: changeme
Upon first login, the system will immediately prompt you to change these details. This is an absolutely crucial security step and must be done immediately.
Section 4: Troubleshooting the “Deploying” Issue: Diagnosis and Repair of Installation Errors
One of the most frequently encountered and frustrating problems when deploying Nginx Proxy Manager on TrueNAS Scale is the situation where the application gets permanently stuck in the “Deploying” state after installation. The user waits, refreshes the page, but the status never changes to “Running”. Viewing the container logs often does not provide a clear answer. This problem is not a bug in NPM itself but, as diagnosed earlier, a symptom of a fundamental permission conflict between the generic container and the specific, secured environment in TrueNAS Scale.
Problem Description and Root Cause
After clicking the “Install” button in the application wizard, TrueNAS Scale begins the deployment process. In the background, the Docker image is downloaded, ixVolumes are created, and the container is started with the specified configuration. The startup script inside the NPM container attempts to perform maintenance operations, including changing the owner of key directories. Because the container is running as a user with limited permissions (apps, UID 568) on a file system it does not fully control, this operation fails. The script halts its execution, and the container never signals to the system that it is ready to work. Consequently, from the perspective of the TrueNAS interface, the application remains forever in the deployment phase.
Fortunately, thanks to the work of the community and developers, there are proven and effective solutions to this problem. Interestingly, the evolution of these solutions perfectly illustrates the dynamics of open-source software development.
Solution 1: Using an Environment Variable (Recommended Method)
This is the modern, precise, and most secure solution to the problem. It was introduced by the creators of the NPM container specifically in response to problems reported by users of platforms like TrueNAS Scale. Instead of escalating permissions, the container is instructed to skip the problematic step.
To implement this solution:
During the application installation (or while editing it if it has already been created and is stuck), navigate to the Application Configuration section.
Find the Nginx Proxy Manager Configuration subsection and click Add next to Additional Environment Variables.
Configure the new environment variable as follows:
Variable Name: SKIP_CERTBOT_OWNERSHIP
Variable Value: true
Save the configuration and install or update the application.
Adding this flag informs the Certbot startup script inside the container to skip the chown (change owner) step for its configuration files. The script proceeds, the container starts correctly and reports readiness, and the application transitions to the “Running” state. This is the recommended method for all newer versions of TrueNAS Scale (Electric Eel, Dragonfish, and later).
Solution 2: Changing the User to Root (Historical Method)
This solution was the first one discovered by the community. It is a more “brute force” method that solves the problem by granting the container full permissions. Although effective, it is considered less elegant and potentially less secure from the perspective of the principle of least privilege.
To implement this solution:
During the installation or editing of the application, navigate to the User and Group Configuration section.
Change the value in the User ID field from the default 568 to 0.
Leave the Group ID unchanged or also set it to 0.
Save the configuration and deploy the application.
Setting the User ID to 0 causes the process inside the container to run with root user permissions. The root user has unlimited permissions, so the problematic chown operation executes flawlessly, and the container starts correctly. This method was particularly necessary in older versions of TrueNAS Scale (e.g., Dragonfish) and is documented as a working workaround. Although it still works, the environment variable method is preferred as it does not require escalating permissions for the entire container.
Verification
Regardless of the chosen method, after saving the changes and redeploying the application, you should observe its status in the Apps -> Installed tab. After a short while, the status should change from “Deploying” to “Running”, which means the problem has been successfully resolved and Nginx Proxy Manager is ready for configuration.
Section 5: Practical Application: Securing a Jellyfin Media Server
Theory and correct installation are just the beginning. The true power of Nginx Proxy Manager is revealed in practice when we start using it to manage access to our services. Jellyfin, a popular, free media server, is an excellent example to demonstrate this process, as its full functionality depends on one, often overlooked, setting in the proxy configuration. The following guide assumes that Jellyfin is already installed and running on the local network, accessible at IP_ADDRESS:PORT (e.g., 192.168.1.10:8096).
Step 1: DNS Configuration
Before NPM can direct traffic, the outside world needs to know where to send it.
Log in to your domain’s management panel (e.g., at your domain registrar or DNS provider like Cloudflare).
Create a new A record.
In the Name (or Host) field, enter the subdomain that will be used to access Jellyfin (e.g., jellyfin).
In the Value (or Points to) field, enter the public IP address of your home network (your router).
Step 2: Obtaining an SSL Certificate in NPM
Securing the connection with HTTPS is crucial. NPM makes this process trivial, especially when using the DNS Challenge method, which is more secure as it does not require opening any ports on your router.
In the NPM interface, go to SSL Certificates and click Add SSL Certificate, then select Let’s Encrypt.
In the Domain Names field, enter your subdomain, e.g., jellyfin.yourdomain.com. You can also generate a wildcard certificate at this stage (e.g., *.yourdomain.com), which will match all subdomains.
Enable the Use a DNS Challenge option.
From the DNS Provider list, select your DNS provider (e.g., Cloudflare).
In the Credentials File Content field, paste the API token obtained from your DNS provider. For Cloudflare, you need to generate a token with permissions to edit the DNS zone (Zone: DNS: Edit).
Accept the Let’s Encrypt terms of service and save the form. After a moment, NPM will use the API to temporarily add a TXT record in your DNS, which proves to Let’s Encrypt that you own the domain. The certificate will be generated and saved.
Step 3: Creating a Proxy Host
This is the heart of the configuration, where we link the domain, the certificate, and the internal service.
In NPM, go to Hosts -> Proxy Hosts and click Add Proxy Host.
A form with several tabs will open.
“Details” Tab
Domain Names: Enter the full domain name that was configured in DNS, e.g., jellyfin.yourdomain.com.
Scheme: Select http, as the communication between NPM and Jellyfin on the local network is typically not encrypted.
Forward Hostname / IP: Enter the local IP address of the server where Jellyfin is running, e.g., 192.168.1.10.
Forward Port: Enter the port on which Jellyfin is listening, e.g., 8096.
Websocket Support: This is an absolutely critical setting. You must tick this option. Jellyfin makes extensive use of WebSocket technology for real-time communication, for example, to update playback status on the dashboard or for the Syncplay feature to work. Without WebSocket support enabled, the Jellyfin main page will load correctly, but many key features will not work, leading to difficult-to-diagnose problems.
“SSL” Tab
SSL Certificate: From the drop-down list, select the certificate generated in the previous step for the Jellyfin domain.
Force SSL: Enable this option to automatically redirect all HTTP connections to secure HTTPS.
HTTP/2 Support: Enabling this option can improve page loading performance.
After configuring both tabs, save the proxy host.
Step 4: Testing
After saving the configuration, Nginx will reload its settings in the background. It should now be possible to open a browser and enter the address https://jellyfin.yourdomain.com. You should see the Jellyfin login page, and the connection should be secured with an SSL certificate (a padlock icon will be visible in the address bar).
The default configuration is fully functional, but to enhance security, you can add extra HTTP headers that instruct the browser on how to behave. To do this, edit the created proxy host and go to the Advanced tab. In the Custom Nginx Configuration field, you can paste additional directives.
It’s worth noting that NPM has a quirk: add_header directives added directly in this field may not be applied. A safer approach is to create a Custom Location for the path / and paste the headers in its configuration field.
The following table presents recommended security headers.
Header
Purpose
Recommended Value
Notes
Strict-Transport-Security
Forces the browser to communicate exclusively over HTTPS for a specified period.
A historical header intended to protect against Cross-Site Scripting (XSS) attacks.
add_header X-XSS-Protection “0” always;
The header is obsolete and can create new attack vectors. Modern browsers have better, built-in mechanisms. It is recommended to explicitly disable it (0).
Applying these headers provides an additional layer of defence and is considered good practice in securing web applications. However, it is critical to use up-to-date recommendations, as in the case of X-XSS-Protection, where blindly copying it from older guides could weaken security.
Section 6: Conclusions and Next Steps
Combining Nginx Proxy Manager with the TrueNAS Scale platform creates an incredibly powerful and flexible environment for managing a home lab. As demonstrated in this report, this synergy allows for centralised access management, a drastic simplification of the deployment and maintenance of SSL/TLS security, and a professionalisation of the way users interact with their self-hosted services. The key to success, however, is not just blindly following instructions, but above all, understanding the fundamental principles of how both technologies work. The awareness that applications in TrueNAS Scale operate within a restrictive ecosystem is essential for effectively diagnosing and resolving specific problems, such as the “Deploying” stall error.
Summary of Strategic Benefits
Deploying NPM on TrueNAS Scale brings tangible benefits:
Centralisation and Simplicity: All incoming requests are managed from a single, intuitive panel, eliminating the chaos of multiple IP addresses and ports.
Enhanced Security: Automation of SSL certificates, hiding the internal network topology, and the ability to implement advanced security headers create a solid first line of defence.
Professional Appearance and Convenience: Using easy-to-remember, personalised subdomains (e.g., media.mydomain.co.uk) instead of technical IP addresses significantly improves the user experience.
Recommendations and Next Steps
After successfully deploying Nginx Proxy Manager and securing your first application, it is worth exploring its further capabilities to fully utilise the tool’s potential.
Explore Access Lists: NPM allows for the creation of Access Control Lists (ACLs), which can restrict access to specific proxy hosts based on the source IP address. This is an extremely useful feature for securing administrative panels. For example, you can create a rule that allows access to the TrueNAS Scale interface or the NPM panel itself only from IP addresses on the local network, blocking any access attempts from the outside.
Backup Strategy: The Nginx Proxy Manager configuration, stored in the ixVolume, is a critical asset. Its loss would mean having to reconfigure all proxy hosts and certificates. TrueNAS Scale offers built-in tools for automating backups. You should configure a Periodic Snapshot Task for the dataset containing the NPM application data (ix-applications/releases/nginx-proxy-manager) to regularly create snapshots of its state.
Securing Other Applications: The knowledge gained during the Jellyfin configuration is universal. It can now be applied to secure virtually any other web service running in your home lab, such as Home Assistant, a file server, a personal password manager (e.g., Vaultwarden, which is a Bitwarden implementation), or the AdGuard Home ad-blocking system. Remember to enable the Websocket Support option for any application that requires real-time communication.
Monitoring and Diagnostics: The NPM interface provides access logs and error logs for each proxy host. Regularly reviewing these logs can help in diagnosing access problems, identifying unauthorised connection attempts, and optimising the configuration.
Mastering Nginx Proxy Manager on TrueNAS Scale is an investment that pays for itself many times over in the form of increased security, convenience, and control over your digital ecosystem. It is another step on the journey from a simple user to a conscious architect of your own home infrastructure.
Imagine a music service that not only stores your entire collection in lossless quality but also displays synchronised lyrics in real time, turning every listening session into a karaoke singalong. What’s more, it’s completely yours – free from adverts, subscriptions, and algorithmic tracking. This isn’t a futuristic vision but a completely achievable reality thanks to the power of open-source software. We can confirm: the karaoke feature works perfectly in both the Jellyfin web interface and the Finamp app on an iPhone. This comprehensive guide will walk you through every stage of building such a system – from installation to creating your own lyric files.
In an era dominated by streaming giants, a movement of “self-hosting” enthusiasts is growing – people who independently manage their own data and services. Instead of entrusting their digital identity to corporations, they build their own private clouds, media servers, and much more. This article is the essence of that philosophy, showing you how to reclaim control over your music and enrich it with features you’d be hard-pressed to find with the competition.
The Architecture of Your Private Spotify: Key Components
Before we delve into the configuration, we need to understand the foundations on which we’ll build our music centre. Success depends on the harmonious collaboration of three key elements.
Jellyfin (Server Version 10.9+): This is the brain of the entire operation. Jellyfin is a free media server that catalogues and serves your music files. Version 10.9 was revolutionary, introducing a standardised, server-managed approach to handling song lyrics. This means all the “heavy lifting” involved in sourcing and processing lyrics happens on the server, and the client applications simply consume the ready-to-use data.
TrueNAS SCALE: This is a reliable and powerful operating system for your home server (NAS). Built on Linux, it offers official support for running applications like Jellyfin in isolated containers, which guarantees stability, security, and order in the system.
Finamp and Jellyfin App (Mobile Clients): These are your windows to the world of music. Finamp, especially in its redesigned beta version, is a favourite among iPhone users as it eliminates the problem of music stopping when the screen goes dark and handles displaying lyrics perfectly. Equally important, the latest versions of the official Jellyfin app also flawlessly support the synchronised lyrics feature.
The Magic of Synchronised Lyrics: The Anatomy of an .lrc File
Confirming that the karaoke feature works is exciting. To make full use of it, you need to understand where this “magic” comes from. The effect of highlighting text in perfect synchronisation with the music depends on the format of the downloaded file. The heart of this mechanism is a simple text file with an .lrc extension.
Synchronised Lyrics (.lrc/.elrc): This is the Holy Grail for karaoke fans. These files contain not only the song’s words but also precise time markers for each line.
Unsynchronised Lyrics (.txt): This is a simpler form, containing plain text. In this case, the application will simply scroll through it smoothly as the song plays, without highlighting individual verses.
The structure of an .lrc file is incredibly simple. Each line of text is preceded by a time marker in the format [minutes:seconds.hundredths of a second].
Example of an .lrc file structure:
[ar: Song Artist]
[ti: Song Title]
[al: Album]
[00:15.50]The first line of text appears after 15.5 seconds.
[00:19.25]The second line of text comes in after 19.25 seconds.
Become a Lyric Creator: How to Create Your Own .lrc File
What if the LrcLib plugin can’t find the lyrics for your favourite niche song? Don’t worry! You can very easily create one yourself.
Get the lyrics: Find the song’s words online and copy them.
Open a text editor: Use any simple editor, like Notepad (Windows) or TextEdit (macOS).
Synchronise with the music: Play the song and pause it at the beginning of each line to note the exact time (minutes and seconds).
Format the file: Before each line of text, add the noted time in square brackets, e.g., [01:23.45]. The more accurate the hundredths of a second, the smoother the effect.
Save the file: This is the most important step. Save the file in the same folder as the audio file, giving it the exact same name but changing the extension to .lrc.
If the music file is: My Super Song.flac
The lyric file must be called: My Super Song.lrc
After saving the file, all you need to do is re-scan your library in Jellyfin, and the server will automatically detect and link your manually created lyrics with the song.
Server Configuration – A Step-by-Step Guide
1. Installing the LrcLib Plugin
In the Jellyfin dashboard, go to Plugins > Catalogue.
Search for and install the official “LrcLib” plugin from the Jellyfin repository. Avoid the outdated jellyfin-lyrics-plugin by Felitendo, which is no longer being developed and may cause errors.
Be sure to restart the Jellyfin server for the changes to take effect.
2. The Most Important Library Configuration
This is a crucial, though unintuitive, step. By default, Jellyfin hides downloaded lyrics in a metadata folder, creating a “black box”. We’ll change this to have full control.
Go to Dashboard > Libraries…
Find your music library, click the menu (three dots), and select Manage library.
In the library settings, tick the option “Save lyrics to media folders”.
3. Starting the Process
Go to Dashboard > Scheduled tasks.
Find the task “Download missing lyrics” and run it manually. Set a schedule (e.g., daily) so that newly added music is processed automatically.
Once the task is finished, run a new scan of the music library.
When Something Goes Wrong – Advanced Troubleshooting
Even with an ideal configuration, you might encounter problems. Here’s how to deal with them.
First Rule of Diagnosis: Always check if the lyrics are visible in the Jellyfin web interface in a browser before you start looking for problems in the mobile app. If they’re not on the server, the problem isn’t on the client side.
Troubleshooting Scanning and Metadata Refreshing: Sometimes, due to the specifics of the system’s operation, the Jellyfin user interface or database doesn’t refresh immediately after the first scan. This manifests as the lyrics still not being visible despite having completed all the steps. The solution is to run a second scan, this time selecting the more detailed “Search for missing metadata” option for the given library. This extra step often forces the system to re-analyse the folders and register the new .lrc files.
The Ultimate Weapon – Manual Cache Cleaning: The most persistent problem is Jellyfin’s aggressive metadata caching. The system creates an internal copy of the lyrics and often refuses to update it, even if the source .lrc file is changed. A simple refresh from the interface can be unreliable. The only 100% effective method is to manually delete the cached file from the server’s file system.
Locate the Jellyfin configuration path on your TrueNAS server (e.g., /mnt/pool/ix-applications/jellyfin/config).
Launch the Shell in the TrueNAS interface.
Navigate to the lyrics cache directory using the cd command and your path: cd /mnt/pool/ix-applications/jellyfin/config/metadata/lyrics.
Find and delete the problematic file using the find command. Replace “Song Title.lrc” with the actual file name: find -type f -name “Song Title.lrc” -print -delete. The -print flag will display the file before it’s deleted.
In the Jellyfin interface, for the given song, select Refresh metadata with the Search for missing metadata mode. Jellyfin, forced into action, will download and process the lyrics anew.
Long-Term Maintenance and Next Steps
Tagging Hygiene: The effectiveness of downloading lyrics depends on the quality of your music’s metadata. Use tools like MusicBrainz Picard to ensure your files have accurate and consistent tags.
Backups: Regularly back up your entire Jellyfin configuration folder (e.g., /mnt/pool/ix-applications/jellyfin/config) to protect your settings, metadata, and user data in case of failure.
External Access: Once you’ve mastered local streaming, the natural next step is to configure secure access from outside your home using Nginx Proxy Manager.
Congratulations! You’ve just built a fully functional, private, and significantly more powerful equivalent of commercial streaming services, with a sensational karaoke feature that will liven up any party or solo evening with headphones.
TrueNAS Scale, with its powerful web interface, makes installing and managing applications simple and intuitive. However, any advanced user will sooner or later discover that the real power and flexibility lie in the command line. It’s worth noting that since version 24.04 (Electric Eel), TrueNAS Scale has undergone a significant transformation, moving away from the previous k3s system (a lightweight Kubernetes distribution) in favour of native container management using Docker. This change has significantly simplified the architecture and made working directly with containers more accessible.
True freedom comes from a direct SSH connection, which bypasses the limitations of the in-browser terminal. It allows you to transform from a regular user into a knowledgeable administrator who can look ‘under the bonnet’ of any application, diagnose problems in real-time, and manage the system with a precision unavailable from the graphical user interface. This article is a comprehensive guide to managing applications in TrueNAS Scale using the terminal, based on the native Docker commands that have become the new foundation of the application system.
Step 1: Identifying Running Applications
Before we can start managing applications, we need to know what is actually running on our system. The graphical interface shows us the application names, but the terminal gives us insight into the actual containers.
Listing Containers: docker ps
The basic command is docker ps. It displays a list of all currently running containers.
docker ps
The output of this command is a table with key information:
CONTAINER ID: A unique identifier.
IMAGE: The name of the image from which the container was created.
STATUS: Information on how long the container has been running.
PORTS: Port mappings.
NAMES: The most important piece of information for us – the user-friendly name of the container, which we will use in subsequent commands (e.g., ix-jellyfin-jellyfin-1).
If you also want to see stopped containers, add the -a flag: docker ps -a.
Monitoring Resources in Real-Time: docker stats
An even better way to get a quick overview is docker stats. This command displays a dynamic, live-updating table showing CPU, RAM, and network resource usage for each container. It’s the perfect tool to identify at a glance which application is putting a load on the system.
docker stats
Step 2: Getting Inside a Container – docker exec
Once you’ve identified a container, you can get inside it to browse files, edit configurations, or perform advanced diagnostics.
docker exec -it ix-jellyfin-jellyfin-1 /bin/bash
Let’s break down this command:
docker exec: Execute a command in a running container.
-it: Key flags that signify an interactive session (-i) with a pseudo-terminal allocated (-t).
ix-jellyfin-jellyfin-1: The name of our container.
/bin/bash: The command we want to run inside – in this case, the Bash shell.
After running the command, the terminal prompt will change, indicating that you are now “inside”. You can move freely around the container’s file system using commands like ls, cd, etc. To exit and return to TrueNAS, simply type exit or use the shortcut Ctrl + D.
Why are Tools like top, ps, or nano Missing?
While working inside a container, you might encounter command not found errors. This is intentional. Many modern Docker images (including the official Jellyfin one) are so-called minimalist or “distroless” images. They do not contain any additional tools, only the application itself and its libraries. This is a best practice that increases security and reduces the image size.
In such cases, you must rely on the external tools provided by Docker itself.
Step 3: Diagnostics and Troubleshooting
When an application isn’t working correctly, the terminal is your best friend.
Viewing Logs: docker logs
This is the most important diagnostic command. It displays everything the application has written to its logs.
docker logs ix-nextcloud-nextcloud-1
If you want to follow the logs in real-time, add the -f (--follow) flag:
docker logs -f ix-nextcloud-nextcloud-1
Detailed Inspection: docker inspect
The docker inspect command returns a vast amount of detailed information about a container in JSON format – its IP address, attached volumes, environment variables, and much more.
docker inspect ix-tailscale-tailscale-1
Step 4: Managing Files and the Application Lifecycle
The terminal gives you full control over the files and the state of your applications.
Copying Files: docker cp
This is an extremely useful command for transferring files between the TrueNAS system and a container, without needing to go inside it.
Copying from a container to TrueNAS (e.g., for a configuration backup):
Instead of clicking in the graphical interface, you can quickly manage your applications:
To stop an application:
docker stop ix-qbittorrent-qbittorrent-1
To start a stopped application:
docker start ix-qbittorrent-qbittorrent-1
To restart an application (the most common operation):
docker restart ix-qbittorrent-qbittorrent-1
From User to Administrator
Mastering a few basic Docker commands in the SSH terminal opens up a whole new dimension of managing TrueNAS Scale. You are no longer dependent on the limitations of the graphical interface and gain the tools to understand how your applications really work.
The ability to quickly check logs, monitor resources in real-time, edit any configuration file, or make a swift backup – all this makes working with the system more efficient and troubleshooting faster. Connecting via SSH is not just a convenience; it’s a fundamental tool for any conscientious administrator who wants full control over their server.
