TrueNAS Print Server: Running CUPS as an App

Running a TrueNAS print server means deploying a service such as CUPS as an app. This guide uses the custom Docker app interface documented for TrueNAS 25.10 and keeps the printer configuration separate from the appliance’s file-sharing service.

The main decisions are printer compatibility, persistent storage, device access and network discovery. The container image determines which drivers and discovery services are available; the Compose outline below is a configuration example, not a verified image recommendation.

First, check whether you need one at all

A print server solves a problem many networks no longer have. Before building anything, work out which situation applies.

IPP Everywhere is designed for driverless network printing between compatible printers and clients. Adding CUPS in that case introduces a queue that can jam, a container that can fail an update, and a dependency on the NAS being up in order to print.

The two cases where it genuinely pays off are a USB-only printer that several machines need, and an older network printer you want to reach from phones and tablets that expect AirPrint.

What the deployment actually consists of

CUPS runs as a single container. Its administration interface listens on port 631. It needs three things to be useful, and each is a decision on the TrueNAS side:

1. Persistent configuration. CUPS writes its printer definitions and settings under /etc/cups, and its spool under /var/spool/cups. Mount the image’s documented paths on persistent storage; data left only in the container’s writable layer can disappear when it is replaced.
2. Access to the printer. For a network printer, ordinary outbound networking. For a USB printer, the container needs the USB device passed through from the host.
3. Discoverability. Automatic discovery needs a DNS-SD advertisement and a working multicast path. Publishing the CUPS web port does not provide either.

Getting all three right is the whole project. Each maps onto a specific option in the TrueNAS app installer.

Deploying it via Compose

The guided Custom App form covers image, ports, storage and a fixed set of options. Anything involving device passthrough needs the YAML route, because the form exposes GPU allocation but not arbitrary host devices.

From Apps, open Discover, then the three-dot menu, then Install via YAML. That opens the Add Custom App screen, where the app takes a lowercase alphanumeric name and the Compose content goes into the Custom Config field, beginning at a top-level key such as name:, services: or include:.

The documentation is explicit that this route requires working knowledge of Docker Compose and YAML, and that TrueNAS applies only basic YAML syntax validation without checking the configuration parameters before running it. A file that parses cleanly but names a device that does not exist will save successfully and then fail at container start. Write it in a real editor first and check indentation before pasting.

The shape of a CUPS service is small:

services:
  cups:
    image: <cups image>
    network_mode: host
    volumes:
      - /mnt/tank/apps/cups/etc:/etc/cups
      - /mnt/tank/apps/cups/spool:/var/spool/cups
    devices:
      - /dev/bus/usb/001/004:/dev/bus/usb/001/004
    restart: unless-stopped

Substitute your own pool, dataset paths and actual USB node; omit devices for a network printer. Pick an image whose documentation you have read, including its driver, discovery and authentication requirements. Some images initialise their configuration differently, so an empty mount over /etc/cups is not a universal installation recipe.

Storage: persist configuration and define a restore path

TrueNAS offers Host Path mounts against existing storage and ixVolume storage created on the apps pool. Both are persistent. An ixVolume does not inherently lose its configuration on an ordinary app update. Host Path is useful when you want to choose and identify the dataset yourself.

For this example, create named configuration and spool directories before deploying. Confirm the image’s user can write to them and that mounting an empty directory does not hide required defaults. The HBA and boot guide’s deployment handoff explains the distinction between a system configuration export and app-data recovery.

Include the configuration dataset in snapshots and independent backups. Check the restore procedure for the chosen image: the printer definitions, driver packages and image version all matter when recreating the service.

Tmpfs is another storage option, but its contents are temporary. A RAM-backed spool trades persistent queued jobs for memory use and loses those jobs when the container stops. Choose that behaviour deliberately.

AirPrint and Avahi under host networking

A queue that works by IP but never appears in a client picker has a discovery problem. Docker host networking shares the host’s network namespace. It removes the container bridge boundary, but does not start a discovery daemon or enable printer sharing.

CUPS must share the queue and publish suitable DNS-SD service information. On Linux, Avahi commonly supplies the mDNS/DNS-SD service; an image needs working integration with it and any D-Bus service that integration requires. The Avahi documentation separates publishing a service from browsing for it. Having a CUPS process running proves neither is working.

Follow the image’s documented discovery arrangement. Running a second Avahi daemon on the host network can introduce conflicts with a responder already using the same interfaces. Do not mount the host’s D-Bus socket merely to make an error disappear; use an arrangement explicitly supported by the image.

In CUPS, enable sharing for the intended queue as described in OpenPrinting’s sharing guide. Driver support, the queue’s advertised capabilities and client compatibility determine whether an older printer works through AirPrint. Host mode alone cannot turn an unsupported USB printer into an AirPrint device.

Check three layers separately:

1. Open the CUPS interface by the NAS address and port 631 to establish basic reachability.
2. Confirm the queue accepts a job through its IPP address.
3. Check discovery from a client on the same subnet, including multicast filtering and wireless client isolation.

For the host-network arrangement, allow the required IPP and mDNS traffic only on the intended LAN. CUPS uses TCP 631; mDNS uses UDP 5353. Discovery across VLANs needs a separate network design. Avoid enabling unrestricted access from every subnet as a substitute.

Host mode also disables useful port remapping: a second service already listening on TCP 631 can conflict. A bridge arrangement can serve a manually configured IPP address, but automatic LAN discovery needs an additional supported mechanism.

USB printer passthrough to a TrueNAS container

A USB printer needs both a host device node and permission for the container to use it. The Compose devices setting maps a host path into the container. In the example, /dev/bus/usb/001/004 is illustrative: inspect the connected printer and replace both sides with its actual node.

Use this sequence to separate discovery from access:

1. Connect and power on the printer, then identify its USB bus/device entry on the NAS.
2. Confirm the image contains a USB printing backend and the driver or Printer Application required by that model.
3. Add the device mapping and open the app shell. CUPS’s lpinfo -v lists available backends and detected printer URIs.
4. Use the reported printer URI when adding the queue. If the device exists but access fails, check the container user and device permissions.
5. After a printer reconnect or power cycle, repeat the check before assuming the original mapping still works.

USB device numbers can change on re-enumeration. A mapping captured when the container was created may therefore require updating the path and recreating the app. Mapping the whole USB bus directory is broader access and is not, by itself, a guarantee of working hotplug: runtime device permissions and discovery still matter.

Docker documents device cgroup rules separately from device mappings. Follow the image’s hotplug instructions if it supplies them; otherwise treat reconnects as an explicit maintenance step. Avoid privileged mode as a general printer fix.

If the printer appears inside the container but jobs remain queued, distinguish a backend problem from a format problem. The CUPS error log can show whether it failed to open the device or failed while running a filter. A successful device mapping does not prove that a compatible driver is installed.

Driverless IPP Everywhere: when a driver is unnecessary

IPP Everywhere defines driverless printing based on IPP and discoverable printer capabilities. For a compatible network printer, CUPS can query those capabilities instead of relying on a model-specific PPD.

The CUPS administration guide documents selecting the everywhere model for a reachable IPP printer. Use the IPP URI reported by discovery or the printer’s documentation. Guessing a path from another model can leave a queue pointing at the wrong endpoint.

That selection does not provide a missing USB driver. An older USB-only device may still need a model-specific backend, filters or a compatible Printer Application. Check support for the exact model and the container architecture before choosing an image.

Prefer direct client-to-printer IPP when it already meets the need. A CUPS relay is useful when it supplies a shared queue or compatibility layer the printer lacks, and its availability then becomes part of the printing path.

What about sharing the printer over SMB?

Samba itself supports printer sharing. The smb.conf reference documents a [printers] section and the print-related parameters that go with it, and a Samba server configured that way advertises print queues to Windows clients the same way it advertises file shares.

That is not a route to take on TrueNAS. The appliance generates its Samba configuration from its own middleware, and the share types offered in the interface are file shares. A hand-edited smb.conf on an appliance whose configuration is machine-generated is not a persistence path you can rely on across updates, and the SMB share configuration TrueNAS does support is aimed squarely at datasets rather than devices.

If Windows clients need to reach the queue, CUPS handles that itself over IPP, which current Windows versions support natively. That keeps the print configuration inside the container where it is backed up with the rest of the app data.

Troubleshooting queue and discovery failures

The CUPS error log is the right first stop for all of these, and the project’s own documentation covers what its log levels mean and where the configuration directives are defined. Most failures at this stage are CUPS configuration questions rather than TrueNAS ones, and they are answered in the CUPS documentation rather than anywhere in the TrueNAS docs.

Keep it on the LAN

CUPS is an administrative web interface with the ability to execute filters on submitted jobs. There is no reason for it to be reachable from outside the network, and the reflexive move of adding a reverse proxy entry for every app should not extend to this one.

Bind it to the LAN, leave it out of any port forwarding, and reach it over the VPN if remote access is genuinely needed. The same reasoning applies to any custom app deployed through the YAML route, which is a deployment path with deliberately less validation than the catalogue apps get.

Where this fits

A print server is a small app with an outsized number of edge cases, and it is a good illustration of what the custom-app route on TrueNAS can and cannot do. The general mechanics behind it, including what changed when the app backend moved off Kubernetes, are covered in moving apps to Docker. For a provisional allowance for several services together, the TrueNAS RAM and ARC Calculator takes app count as an input and explains its assumptions.

FAQ

Can TrueNAS share a USB printer through CUPS?

Yes, when the custom app has device access and a compatible printing backend. Identify the actual USB node and check it again after reconnecting the printer.

Does host networking automatically enable AirPrint?

No. The queue must be shared, compatible capabilities must be advertised through DNS-SD, and the client must receive that advertisement. Avahi integration and multicast reachability are separate checks.

Does IPP Everywhere work with every USB printer?

No. It describes driverless IPP printing. A legacy USB printer can still require a compatible driver, filter or Printer Application before a shared queue can print successfully.

Does ixVolume lose CUPS settings during updates?

An ixVolume is persistent storage on the apps pool. Missing settings call for checking mount paths, image initialisation and permissions; ordinary persistence does not replace an independent backup.