Design

Context

See proposal.md for motivation - we need to create a Podman container that runs a CUPS print server for Brother HL-4150CDN. The repo contains the Brother driver packages in assets/Brother HL-4150CDN/:

lpr-driver/hl4150cdnlpr-1.1.1-5.i386.deb
cupswrapper/hl4150cdncupswrapper-1.1.1-5.i386.deb
installer/linux-brprinter-installer-2.2.6-0.gz (reference only; we will NOT run it in the build - it is interactive and downloads from the network)

Key observations:

Brother drivers are i386 binaries (32-bit ELF). Container needs 32-bit runtime libraries.
CUPS wrapper + LPR packages provide PPD, filters, and helper binaries.
AirPrint requires CUPS + Avahi/mDNS (DNS-SD).
Brother's cups wrapper installs files to /usr/local/Brother/ and may need symlinks into CUPS directories.

Goals / Non-Goals

Goals:

Create a Containerfile that builds a working image for Podman
Install and configure Brother HL-4150CDN drivers
Share printer via IPP with AirPrint discovery
Expose ports 631 (CUPS/IPP) and 5353/udp (mDNS)
Make it easy to run with podman

Non-Goals:

Managing multiple printers
Custom SSL/TLS configuration for CUPS (use defaults or documented)
Persistent CUPS spool/state beyond basic setup

Decisions

Base image

Use Debian/Ubuntu (or similar) as base to handle .deb packages and 32-bit libs easily. Alternatively Alpine, but Alpine needs musl + 32-bit support can be more complex for prebuilt i386 ELF binaries from Brother. Debian stable is practical.

Driver installation

Use the local .deb packages from assets/Brother HL-4150CDN/ (copied into the build context) and install with dpkg -i --force-all. No network download at build time for the driver itself.
Do not run the Brother installer script (linux-brprinter-installer-2.2.6-0.gz) in the build - it is interactive and downloads packages from download.brother.com.
Also need to install brcupsconfpt1 helper if needed - comes with cups wrapper.
Run the cups wrapper install logic as per Brother installer (or manually create symlinks).

CUPS + Avahi + DBus

Install cups, avahi-daemon, dbus. Run dbus and avahi-daemon; start cupsd.
Configure CUPS to allow remote access/sharing. For containerized setup, typically need to listen on all interfaces and configure sharing.

Printer configuration

Add printer via lpadmin using the Brother PPD. Point to network URI (e.g., ipp://PRINTER_IP/ipp or socket://PRINTER_IP:9100 - depends on printer; HL-4150CDN is network printer).
Enable printer sharing and default options.

Runtime configuration

The printer endpoint and advertised name are supplied through environment variables rather than baked into the image, so the same image can be pointed at any HL-4150CDN:
- PRINTER_IP + PRINTER_PROTOCOL (lpd/socket/ipp) derive the device URI.
- PRINTER_URI overrides the derived URI for full control.
- PRINTER_NAME sets the CUPS queue name and the DNS-SD/AirPrint advertised name.
- PRINTER_DESCRIPTION sets the CUPS Description (Info) shown in the web UI.
The entrypoint builds the URI and runs lpadmin at startup, then shares the queue.

Risks / Trade-offs

[Risk] Brother binaries are 32-bit only → require multiarch libs (libc6:i386, etc.). Increases image size slightly.
[Risk] Using .deb packages assumes glibc-based base. If we choose different base, need to ensure compatibility.
[Risk] Avahi in container needs --net=host or proper mDNS setup. AirPrint discovery typically works better with host network mode; document this.
[Risk] CUPS state (printers.conf, etc.) should be persisted if we want config to survive restarts - may need volumes.

3.6 KiB Raw Blame History