AirPrint on Synology NAS via CUPS Docker

Runbook for setting up AirPrint on a Synology NAS so iOS/macOS devices can print to a USB or network printer over the local network. Uses a Docker CUPS container and Synology’s built-in avahi (mDNS) daemon for service discovery.

Architecture

#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

iPhone
  │  mDNS discovery (_ipp._tcp)
  ▼
Synology avahi-daemon (eth4, port 5353)
  │  reads service files from /etc/avahi/services/
  │
CUPS Docker container (host network, port 631)
  │  generates /etc/avahi/services/AirPrint-*.service
  │  proxies print jobs to printer
  ▼
Printer (e.g. socket://10.0.20.50:9100)

Key design decisions:

• Container uses network_mode: host — required for mDNS broadcast to work
• Container mounts /etc/avahi/services directly so Synology’s avahi picks up its service files
• Synology’s own CUPS must be disabled to free port 631

Prerequisites

#

• Synology DSM with Docker (Container Manager) installed
• SSH access to NAS
• Printer reachable from NAS (USB or network socket)
• Disable Synology’s built-in CUPS print server (via DSM package or synoservicectl)

Setup

#

1. Create directory structure

#

1

mkdir -p /volume1/docker/cups/config

2. docker-compose.yaml

#

Create /volume1/docker/cups/docker-compose.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

version: '3'
services:
  cups-airprint:
    image: tigerj/cups-airprint:latest
    container_name: cups-airprint
    network_mode: "host"
    environment:
      - CUPSADMIN=admin
      - CUPSPASSWORD=yourpassword
    volumes:
      - /volume1/docker/cups/config:/config
      - /etc/avahi/services:/services   # let container manage avahi service files
    restart: unless-stopped

3. Start the container

#

1
2

cd /volume1/docker/cups
docker-compose up -d

4. Add your printer via CUPS web UI

#

Open http://<nas-ip>:631 in a browser, log in with the admin credentials, and add your printer:

• Administration → Add Printer
• For a network printer: socket://10.0.x.x:9100
• Set Shared: Yes
• Choose the appropriate PPD/driver (Gutenprint works well for most Brother/HP printers)

The container’s printer-update.sh watches for CUPS printer changes and automatically regenerates the avahi service file in /etc/avahi/services/.

5. Verify mDNS broadcast

#

1
2

avahi-browse -a -t | grep -i airprint
# should show: AirPrint <PrinterName> @ Synology   _ipp._tcp   local

6. Verify CUPS is accessible

#

1
2

curl http://<nas-ip>:631/printers/
# should list your printer as Idle

Debugging Notes

#

Container uses wrong volume mount after yaml edit

#

If you edit docker-compose.yaml to change the /services mount, you must recreate (not just restart) the container for it to take effect:

1

docker-compose down && docker-compose up -d

Verify the active mounts:

1
2

docker inspect cups-airprint --format '{{json .Mounts}}'
# Source for /services destination should be /etc/avahi/services

Printer not showing on iOS

#

Check in order:

1. avahi-browse -a -t | grep ipp — is the service being advertised?
2. curl http://nas-ip:631/printers/ — is CUPS serving the printer?
3. Firewall — DSM firewall may block port 631 from device subnets
4. docker inspect cups-airprint — confirm network_mode is host
5. Force iOS to re-scan: toggle Wi-Fi off/on, or open an app’s print dialog

avahi only broadcasts on one interface

#

Check /etc/avahi/avahi-daemon.conf — Synology locks avahi to allow-interfaces=eth4 (the main LAN port). This is correct for a single-NIC setup. If your LAN is on a different interface, update that line (but DSM may reset it on upgrade).

Port 631 already in use

#

Synology’s CUPS may still be running. Stop it:

1
2

synoservicectl --stop cups
synoservicectl --stop cups-lpd   # if present

My Setup

#

Notes

#

• The URF=none TXT record in the avahi service file is expected for older printers using traditional CUPS drivers — iOS will still discover and use the printer
• The avahi service file is auto-regenerated on container start and on any CUPS printer state change, so no manual editing is needed
• docker-compose.yaml is the source of truth — always recreate (not restart) after volume changes