CUPS Print Server Image

Overview

This project extends the olbat/cupsd Docker image with additional features for better USB printer management and persistent configuration.

Extensions to the Original Project

This fork adds the following improvements to the original CUPS Docker image:

1. Persistent Configuration: CUPS configuration is now persisted using a Docker volume (cups-data) that maps to the local ./cups directory, ensuring your printer settings survive container restarts.

2. USB Printer Hot-Plugging: Enhanced entrypoint script that monitors USB printer connections and automatically restarts the CUPS daemon when printers are reconnected. This solves issues with USB printers that become unavailable after being disconnected and reconnected.

3. Multiple Printer Support: Monitor multiple USB printers simultaneously using comma-separated vendor and product IDs.

4. Docker Compose Setup: Simplified deployment using Docker Compose instead of manual docker commands.

5. Configurable Base Image: Easily change the underlying CUPS base image version using the CUPSD_TAG environment variable.

6. Privileged Mode: Runs with necessary privileges for USB device access and udev functionality.

7. udev Support: Proper USB device management and permissions for reliable hot-plugging.

Quick Start with Docker Compose

The easiest way to run this CUPS server is using Docker Compose:

# Start the CUPS server
docker-compose up -d

# View logs
docker-compose logs -f cupsd

# Stop the server
docker-compose down

Configuration

You can customize the USB printer detection by setting environment variables. The easiest way is to use a .env file:

# Copy the example environment file
cp example.env .env

# Edit the .env file with your printer's USB IDs
nano .env

Environment Variables

• CUPSD_TAG: Version of the olbat/cupsd base image to use (default: stable-2025-07-28)
• VENDOR_ID: Your printer's USB vendor ID(s) (required)
• PRODUCT_ID: Your printer's USB product ID(s) (required)
• CHECK_INTERVAL: How often to check for USB printer connection (default: 10 seconds)

Single Printer Configuration

Example .env file for one printer:

# Base image version
CUPSD_TAG=stable-2025-07-28

# Your printer's USB vendor and product IDs
VENDOR_ID=04e8
PRODUCT_ID=328b

# Optional: Check interval in seconds (default: 10)
CHECK_INTERVAL=10

Multiple Printers Configuration

Example .env file for multiple printers:

# Base image version
CUPSD_TAG=stable-2025-07-28

# Multiple printers - comma-separated vendor and product IDs
VENDOR_ID=04e8,1234,5678
PRODUCT_ID=328b,abcd,efgh

# Optional: Check interval in seconds (default: 10)
CHECK_INTERVAL=10

Important: When using multiple printers, ensure the number of vendor IDs matches the number of product IDs. Each pair will be combined as vendor:product (e.g., 04e8:328b, 1234:abcd, 5678:efgh).

To find your printer's USB IDs, use:

lsusb

Security Note

This container runs in privileged mode to enable USB device hot-plugging. This is necessary for proper USB device access and udev functionality.

Manual Docker Run (Original Method)

Using the default cupsd.conf configuration file:

docker run -d -p 631:631 -v /var/run/dbus:/var/run/dbus --name cupsd olbat/cupsd

Using a custom cupsd.conf configuration file:

docker run -d -p 631:631 -v /var/run/dbus:/var/run/dbus -v $PWD/cupsd.conf:/etc/cups/cupsd.conf --name cupsd olbat/cupsd

Note: the following mount can be added to configure a printer connected through USB -v /dev/bus/usb:/dev/bus/usb see https://github.com/olbat/dockerfiles/issues/103#issuecomment-2187149476

Note (bis): if the daemon fails to start with a cupsdDoSelect() failed error, you can fix the issue by adjusting the container's ulimit configuration, see https://github.com/olbat/dockerfiles/issues/111#issuecomment-2529393079

Add printers to the Cups server

1. Connect to the Cups server at http://127.0.0.1:631
2. Add printers: Administration > Printers > Add Printer

Note: The admin user/password for the Cups server is print/print

Configure Cups client on your machine

1. Install the cups-client package
2. Edit the /etc/cups/client.conf, set ServerName to 127.0.0.1:631
3. Test the connectivity with the Cups server using lpstat -r
4. Test that printers are detected using lpstat -v
5. Applications on your machine should now detect the printers!

Included package

• cups, cups-client, cups-filters
• foomatic-db
• printer-driver-all, printer-driver-cups-pdf
• openprinting-ppds
• hpijs-ppds, hp-ppd
• sudo, whois
• smbclient
• udev, systemd-sysv (for USB device management)

Troubleshooting

This Dockerfile can be used to build an image is containing most of the printing drivers packaged by Debian's team and allows to run a CUPS daemon to create a remote print server.

Common Issues

"Waiting for printer to become available"

• Ensure the container is running in privileged mode
• Check USB device detection: docker exec cupsd lsusb
• Verify device permissions: docker exec cupsd ls -la /dev/bus/usb/

USB Device Not Detected

• Ensure privileged mode is enabled in docker-compose.yml
• Check that udev is running: docker exec cupsd ps aux | grep udev
• Verify USB passthrough is working properly

Now, this is as good as it gets! This repository has nothing to do with maintaining/debugging/supporting printer drivers packaged in Debian or the CUPS service.

If you need support on those topics, please try to reach out to the relevant support channels:

• Debian forums
• Debian "printing" team
• cups mailing list
• or one of the many other options you could easily find using your favorite search engine!

If you have some questions about how to start the container, make it accessible through your local network, run it on your NAS, etc. again, this is not the good place to ask them.

In that case, please reach out to the relevant support channels. If you have an issue related to Docker's networking, I also strongly advise you to have a look at Docker's documentation page on that topic to get a good grasp on the main concepts in play.