# 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.