CUPS Web: A Self-Hosted Print Queue Manager for Small Offices
CUPS Web is a self-hosted web interface for managing printers and print queues with CUPS.
At a glance
- What is it?
- CUPS Web wraps CUPS in a browser-based administration and printing interface with multi-user support, driver management, and automatic document conversion. It is a practical fit for home and small office setups, but its root-level driver installation and single-task limit demand careful operation.
- Who is it for?
- Adopt CUPS Web if you run a home or small office with CUPS and want a browser-based way to submit print jobs, manage users, and install drivers without SSH. Do not use it in a multi-tenant or untrusted environment, because the admin account can install .deb packages that execute as root, and the driver persistence volume must be backed up.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 14, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What CUPS Web Actually Solves
CUPS Web addresses a gap in the CUPS ecosystem: the default CUPS web interface is functional but sparse, and command-line administration is not accessible to non-technical users. This project provides a self-hosted web application that lets users upload files, choose a printer, set options like duplex and color, and submit jobs. It also offers an admin panel for user management and print log tracking. The target audience is households and small offices where one person manages printers but others need to print without learning lpadmin or editing PPD files. The README explicitly states it is suited for family and small office use, not for large enterprises.
How It Works: Conversion, IPP, and the Stack
The backend is written in Go 1.26 and uses Gorilla Mux for routing. Print jobs are sent to CUPS via the IPP protocol using the OpenPrinting/goipp library, which is a direct integration rather than shelling out to lp commands. Document conversion is a key mechanism: Office files are converted to PDF via LibreOffice, OFD files via a Java-based converter (ofdrw) running on Java 21, and images or text are rendered to PDF server-side. The frontend is Vue 3 with Vite and Nuxt UI, using hash-based routing. SQLite is used for storing users, print logs, and session data, with the pure-Go modernc.org/sqlite driver, so no CGO is required. The CUPS server inside the image is compiled from source version 2.4.x, which the README notes overrides the apt-provided version.
Getting It Running: Docker Compose and Environment Variables
The recommended deployment is Docker Compose. The README provides a compose file that maps ports 631 (CUPS) and 1180 (web UI), and mounts several volumes: ./.etc for /etc/cups, ./.data for /data, ./.uploads for /uploads, and ./.drivers for /opt/cups-drivers/data. It also mounts the host's D-Bus socket, USB bus, and udev directory, which are needed for printer discovery and USB access. The container runs as root, and the compose file includes security_opt: apparmor:unconfined, which is a notable security relaxation. Environment variables CUPSADMIN and CUPSPASSWORD set the CUPS admin credentials, defaulting to 'print' and 'print'. After starting with docker compose up -d, you access the web UI at http://localhost:1180 and log in with the default admin/admin credentials. The README warns that the admin account is protected and cannot be deleted or renamed.
Driver Management: The Strongest and Most Dangerous Feature
The driver management page is admin-only and provides automatic detection of USB and network printers, one-click installation of matching drivers, and a list of all available drivers with installation status and architecture support. It also accepts uploads of .ppd files or .deb packages. The installation process is asynchronous: the API returns immediately, and the page shows a progress card that refreshes every two seconds with live logs. This is a thoughtful design, but it has sharp edges. The README explicitly warns that only one driver task can run at a time because apt and dpkg hold global locks; a second task is rejected. The hard timeout for background tasks is 30 minutes, and the page waits up to 35 minutes. Drivers that require compilation, such as Canon CAPT or HP foo2zjs firmware, can take minutes to tens of minutes, especially on ARM devices. The README also warns that uploading a .deb executes its installation script as root, effectively making the admin password equivalent to container root credentials. This is a deliberate capability, but it means you should never expose the admin account to untrusted users.
Persistence and the .drivers Volume
Driver persistence is handled through a snapshot mechanism. Installed drivers are saved to the .drivers volume, and on container restart they are restored. For .ppd files, they are copied back to /usr/share/cups/model/custom. For .deb packages, the original package is archived and reinstalled with dpkg -i on startup. The README notes that simply copying the files back would not make the driver work, so the package is reinstalled. This is a pragmatic approach, but it has a failure mode: if a .deb repeatedly fails to install, the container will retry it on every startup, generating warnings in the logs. To remove such a package, you must delete the corresponding file from ./drivers/custom-deb/packages/ on the host. The README is explicit that deleting the .drivers volume or forgetting to mount it means losing all manually installed drivers, so backups must include this directory.
Security Model: Sessions, CSRF, and Role Separation
Authentication uses session cookies signed and encrypted with Gorilla securecookie, with the key auto-generated and persisted in the database. Passwords are hashed with bcrypt. All non-GET/HEAD/OPTIONS requests are checked for an X-CSRF-Token, which protects against cross-site request forgery. There are two roles: admin and user. Regular users can submit print jobs and view their own records, but they cannot access the driver management page or the admin panel. The README states that the user role cannot see or call the driver interfaces. This separation is important because the driver installation endpoint is effectively a root shell. However, the default credentials admin/admin are well-known, so the first step after deployment should be changing them. The README does not mention any rate limiting or brute-force protection, so the web UI is only as secure as the network it is exposed on.
Limitations and When to Avoid It
The most obvious limitation is the single-driver-task constraint. If you have multiple printers needing different drivers, you must install them sequentially, and each may take minutes. The 30-minute timeout could be hit on slow ARM hardware, leaving the driver half-installed. The README warns against refreshing the page during installation, because the live log is lost, though the background task continues. Another limitation is that the driver list is not exhaustive; the README provides a table of optional vendor drivers, but many niche printers are not covered. For those, you must rely on the generic Debian driver packages or upload your own .deb, which carries the root-execution risk. The project is also not designed for large fleets; there is no mention of load balancing, clustering, or multi-server support. If you need centralized printing for hundreds of users, this is the wrong tool.
Alternative Approaches and What to Verify First
The most direct alternative is the built-in CUPS web interface itself, which is simpler and requires no additional software, but it lacks user management, print logging, and the driver installation wizard. Another alternative is PaperCut NG or similar commercial print management systems, which offer quota management, authentication against LDAP or Active Directory, and centralized reporting. The difference is that CUPS Web is self-hosted, open source, and tightly coupled to CUPS, whereas commercial products are heavier and often require a separate server and per-user licensing. Before adopting CUPS Web, verify that your printer models are supported by the preinstalled drivers (such as hplip or printer-driver-all) or that a vendor driver exists for your architecture. Check the architecture column in the README's driver table; for example, Epson's China driver is amd64 only. Also confirm that your host can mount /dev/bus/usb and /run/udev, because without them USB printer discovery will not work.
Editorial conclusion
Adopt CUPS Web if you run a home or small office with CUPS and want a browser-based way to submit print jobs, manage users, and install drivers without SSH. Do not use it in a multi-tenant or untrusted environment, because the admin account can install .deb packages that execute as root, and the driver persistence volume must be backed up. Before deploying, verify that your printer is supported by the preinstalled generic drivers or that a vendor driver exists for your architecture, and confirm that you can mount the required volumes (/etc/cups, /data, /uploads, /opt/cups-drivers/data) and the host's D-Bus, USB, and udev sockets. The 30-minute hard timeout for driver tasks and the one-task-at-a-time limit are real constraints, so plan for asynchronous installation and avoid concurrent actions.
Community notes