About this project

## Project Overview cups-web-print is a web printing service based on Python Flask and CUPS, providing an HTTP graphical interface for CUPS print servers. It can convert a USB printer connected to the server into a network printer, allowing devices on the local network to print through a browser without installing drivers or configuring print queues on each device. ## Key Capabilities ### File Management - Supports PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, TXT, RTF, and image formats such as JPG, JPEG, PNG, GIF, BMP, SVG - Supports drag-and-drop upload - Online preview: PDF preview on desktop, image preview on mobile - File list viewing and deletion ### Print Settings - Paper size: Office A1-A4, photo 5-10 inches, etc. - Paper type: Plain paper, glossy photo paper, etc. - Color mode: Color / Black and white - Duplex printing: Single-sided, double-sided long-edge binding, double-sided short-edge binding - Print orientation: Portrait / Landscape - Number of copies: 1-99 copies - Page range: e.g., 1-5 8 10-12 - Print scaling: Auto / Fit / Fill / No scaling - Page mirroring: Supports horizontal flip ### Task Management - Printer online status detection (limited to IPP printers) - Real-time task status monitoring: Submitted / Processing / Completed / Failed / Cancelled - Task progress display (estimated based on time and CUPS queue) - Task cancellation - Real-time print queue viewing - Tray information, ink cartridge information, printer information (uptime, firmware version, alerts, etc.), all obtained via IPP protocol ### Security Protection - Path traversal attack protection - File type whitelist validation - File size limit of 100MB - Automatic log rotation - Automatic preview cache cleanup when deleting files ### Bilingual Interface - Chinese interface: http://localhost:5000/zh - English interface: http://localhost:5000/en ## Technology Stack - Backend: Python 3.9+ and Flask 3.0+ - Frontend: HTML5 and Tailwind CSS (CDN) - Printing service: CUPS 2.0+ - Document conversion: LibreOffice 6.0+ - PDF processing: poppler-utils (pdftoppm), pdftk - IPP protocol: ipptool (cups-client) ## Compatibility Notes The project uses the IPP standard protocol and CUPS standard commands, theoretically compatible with most printers supporting the IPP protocol. The README states that testing has been completed on the Canon G3881; other printers require self-verification. ## Deployment Methods ### Container Installation (Recommended) Run via Docker, mapping ports 5000 (Web interface) and 631 (CUPS), and mounting CUPS configuration, queues, logs, as well as upload and preview directories. USB printers require privileged mode and USB device mounting; these can be omitted when using only network printers. Example for adding a printer (using a network printer as an example): ``` docker exec cups-web-print lpadmin -p Canon_G3881 -v ipp://192.168.1.16:631/ipp/print -m everywhere -E ``` ### Local Installation Requires installation of cups, cups-client, LibreOffice components, poppler-utils, pdftk, and Python dependencies. Start the CUPS service, add a printer using lpadmin, then run app.py. The README also provides an optional method for auto-start on boot via crontab. ## Directory Structure - app.py: Main Flask application file - ipp_client.py: Retrieves tray, ink cartridge, and other status information via IPP - printer_checker.py: Confirms printer online status via IPP, BJNP, and other protocols - templates/: index.html (Chinese homepage) and index_en.html (English homepage) - uploads/, previews/: Directories for uploaded files and preview files ## Troubleshooting The README provides a fairly complete troubleshooting checklist, covering: lpadmin failure to add printer (including IPP address differences across brands, driverless mode, cupsenable/cupsaccept), port 5000 unresponsive (process, port listening, firewall, Flask binding address), no available printers on the page, document conversion failure, PDF preview generation failure, page range extraction failure, inability to retrieve ink cartridge/tray information, and the "prompts success but no output" situation (requires confirming the -m everywhere parameter, CUPS driver and PPD file, printer idle status, and CUPS logs). ## License GPLv3. The README states that the software is provided "as is," and the author assumes no responsibility for consequences of use.