love4taylor / cups-airprint

Dockerized CUPS/AirPrint

Table of Contents

• About
• Intro
• Multi-arch Image
• Getting Started
  • Docker Run
  • Docker Create
    • Parameters
  • Docker Compose
  • Docker Build
• Using
• Notes
• Trouble Shooting
  • Missing Printer Driver
  • Driver Version

About

Modified copy of source code at: https://github.com/quadportnick/docker-cups-airprint

Intro

This Ubuntu-based Docker image runs a CUPS instance that is meant as an AirPrint relay for printers that are already on the network but not AirPrint capable. The local Avahi will be utilized for advertising the printers on the network.

Multi-arch Image

The below commands reference a Docker Manifest List at love4taylor/cups-airprint built using Docker's BuildKit. Simply running commands using this image will pull the matching image architecture (e.g. amd64, arm32v7, or arm64) based on the hosts architecture. Hence, if you are on a Raspberry Pi the below commands will work the same as if you were on a traditional amd64 desktop/laptop computer. Note: Because the image requires ubuntu as its base image, there is currently no arm32v6 architecture available. This means if your target hardware is a Raspberry Pi Zero or similar arm 6 architecture, this image will not run.

Getting Started

This section will give an overview of the essential options/arguments to pass to docker to successfully run containers from the love4taylor/cups-airprint docker image.

Docker Run

To simply do a quick and dirty run of the cups/airprint container:

$ docker run \
       -d \
       --name=cups \
       --net=host \
       -v /var/run/dbus:/var/run/dbus \
       --device /dev/bus \
       --device /dev/usb \
       -e CUPSADMIN="admin" \
       -e CUPSPASSWORD="password" \
       ghcr.io/love4taylor/cups-airprint:master

To stop the container simply run:

$ docker stop cups

To remove the conainer simply run:

$ docker rm cups

WARNING: Be aware that deleting the container (i.e. cups in the example) will permanently delete the data that docker volume is storing for you. If you want to permanently persist this data, see the docker create example below. Continue reading the Notes section for more details about Docker volumes

• Notes: The Dockerfile explicitly sets volumes at /config and /services (see these lines). The necessary configurations done by the docker container will be stored in those directories and will persist even if the container stops. Docker will store the contents of these directories (located in the container) in /var/lib/docker/volumes (see for reference Docker Volumes).

Docker Create

Creating a container is often more desirable than directly running it:

$ docker create \
       --name=cups \
       --restart=always \
       --net=host \
       -v /var/run/dbus:/var/run/dbus \
       -v ~/airprint_data/config:/config \
       -v ~/airprint_data/services:/services \
       --device /dev/bus \
       --device /dev/usb \
       -e CUPSADMIN="admin" \
       -e CUPSPASSWORD="password" \
       ghcr.io/love4taylor/cups-airprint:master

Follow this with docker start and your cups/airprint printer is running:

$ docker start cups

To stop the container simply run:

$ docker stop cups

To remove the conainer simply run:

$ docker rm cups

• Notes: As mentioned in the Notes subsection of the Run section, the Dockerfile explicitly declares two volumes at /config and /services inside the container as mount points. Here we actually override the default use of Docker's innate volume management system and declare our own path on the host system to mount the two directories /config and /services. Why? Because now if the container is deleted (for any number of reason ...) the data will persist. Here we chose to mount the internal /config and /services directories to ~/airprint_data/config and ~/airprint_data/services respectively, but these could just as well be anywhere on your file system.

Parameters

• --name: gives the container a name making it easier to work with/on (e.g. cups)
• --restart: restart policy for how to handle restarts (e.g. always restart)
• --net: network to join (e.g. the host network)
• -v ~/airprint_data/config:/config: where the persistent printer configs will be stored
• -v ~/airprint_data/services:/services: where the Avahi service files will be generated
• -e CUPSADMIN: the CUPS admin user you want created
• -e CUPSPASSWORD: the password for the CUPS admin user
• --device /dev/bus: device mounted for interacting with USB printers
• --device /dev/usb: device mounted for interacting with USB printers

Docker Compose

If you don't want to type out these long Docker commands, you could optionally use docker-compose to set up your image. Just download the repo and run it like so:

$ git clone https://github.com/love4taylor/cups-airprint
$ cd cups-airprint
$ docker-compose up

NOTE: This compose file is made with USB printers in mind and like the above commands has device mounts for USB printers. If you don't have a USB printer you may want to comment these out. Also the config/services data will be saved to the users $HOME directory. Again you may want to edit this to your own liking.

Docker Build

If you would like to build the image yourself (locally), pull down the repo and run the docker build command as follows:

$ git clone https://github.com/love4taylor/cups-airprint
$ cd cups-airprint
$ docker build -t love4taylor/cups-airprint .

Follow this with a docker run or docker create to deploy your container and your cups-airprint server is ready to be configured and used.

Using

CUPS will be configurable at http://localhost:631 using the CUPSADMIN/CUPSPASSWORD when you do something administrative.

If the /services volume isn't mapping to /etc/avahi/services then you will have to manually copy the .service files to that path at the command line.

Notes

• CUPS doesn't write out printers.conf immediately when making changes even though they're live in CUPS. Therefore it will take a few moments before the services files update
• Don't stop the container immediately if you intend to have a persistent configuration for this same reason

Trouble Shooting

Here we are going to discuss the most common problems that users have when trying to setup and configure their printer to work with the love4taylor/cups-airprint image.

Missing Printer Driver

As you might imagine this is the most common problem users have when setting up their printers. While the love4taylor/cups-airprint image possesses multiple printer drivers, it most likely does not have every driver for every printer. This issue can be resolved as follows:

• Figure out what printer driver you need, open an issue about missing driver, necessary package containing said driver will be added to Dockerfile.

Driver Version

Sometimes the right printer driver is installed in the love4taylor/cups-airprint Docker image, but the version is not current. This issue may require one of two choices to resolve:

• Download the cups-airprint git repo and build a fresh image

  • This will pull the most recent versions of the printer driver from the package manager.

• Download driver DIRECTLY from the manufacturer and add it to the image

  • If building a fresh image does not update the version of the driver, then you will need the most recent printer driver from the manufacturer.