dipievil/cups-print-server repository overview

⁠CUPS Print Server Docker Image

🖨️ A flexible, self-hosted CUPS print server with optional printer driver support for containerized printing solutions.

⁠✨ Features

• 🚀 Quick Setup - Run a CUPS server in seconds
• 🔌 USB Support - Direct USB printer connection
• 🌐 Network Printing - Share printers across your LAN
• 🔧 Modular Design - Base image + optional printer drivers
• 🖨️ Brother Support - Pre-built Brother printer drivers
• 📊 Monitoring - Built-in validation and health checks
• 🐳 Docker Native - Lightweight and portable

⁠🚀 Quick Start

⁠Basic Usage

docker run -d \
  --name cups-server \
  -p 631:631 \
  --device /dev/bus/usb:/dev/bus/usb \
  --privileged \
  -e CUPSADMIN=admin \
  -e CUPSPASSWORD=yourpassword \
  dipi/cups-server:latest

Access CUPS web interface at http://localhost:631

⁠With Docker Compose

version: '3.8'
services:
  cups:
    image: dipi/cups-server:latest
    ports:
      - "631:631"
    devices:
      - /dev/bus/usb:/dev/bus/usb
    privileged: true
    environment:
      - CUPSADMIN=admin
      - CUPSPASSWORD=changeme
    volumes:
      - cups_data:/etc/cups

volumes:
  cups_data:

⁠🏷️ Image Variants

⁠🔧 Environment Variables

⁠🖨️ Brother Printer Support

⁠Option 1: Pre-built Image (Recommended)

docker run -d \
  -p 631:631 \
  --device /dev/bus/usb:/dev/bus/usb \
  --privileged \
  dipi/cups-server:brother

⁠Option 2: Runtime Installation

docker run -d \
  -p 631:631 \
  --device /dev/bus/usb:/dev/bus/usb \
  --privileged \
  -e INSTALL_BROTHER_DRIVER=true \
  -e BROTHER_PRINTER_MODEL=HL-1212W \
  dipi/cups-server:latest

⁠Supported Brother Models

The installer supports most Brother printer models. Common models include:

• HL-1210W, HL-1212W
• HL-2270DW, HL-2280DW
• DCP-L2540DW, DCP-L2550DW
• MFC-L2700DW, MFC-L2720DW

Check Brother's Linux support page⁠ for your specific model.

⁠🔐 USB Device Permissions

For USB printers to work, you need to configure udev rules on the host machine.

⁠Brother Printers

# Create udev rule
cat > /etc/udev/rules.d/99-brother-printer.rules << 'EOF'
# Brother printers - allow CUPS access
SUBSYSTEM=="usb", ATTR{idVendor}=="04f9", MODE="0666", GROUP="lp"
EOF

# Reload udev rules
udevadm control --reload-rules
udevadm trigger

# Reconnect printer

⁠Generic USB Printers

# Allow all USB printers
cat > /etc/udev/rules.d/99-usb-printers.rules << 'EOF'
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", MODE="0666"
EOF

udevadm control --reload-rules
udevadm trigger

⁠📖 Usage Examples

⁠Network Printing

docker run -d \
  --name cups-server \
  --network host \
  -e CUPSADMIN=admin \
  -e CUPSPASSWORD=secure123 \
  dipi/cups-server:latest

⁠Persistent Configuration

docker run -d \
  --name cups-server \
  -p 631:631 \
  --device /dev/bus/usb:/dev/bus/usb \
  --privileged \
  -v cups_config:/etc/cups \
  -v cups_spool:/var/spool/cups \
  dipi/cups-server:latest

⁠Custom CUPS Configuration

docker run -d \
  --name cups-server \
  -p 631:631 \
  -v $(pwd)/cupsd.conf:/etc/cups/cupsd.conf:ro \
  dipi/cups-server:latest

⁠🏗️ Building from Source

# Clone repository
git clone https://github.com/dipievil/cups-print-server.git
cd cups-print-server

# Build base image
docker build -t cups-server:latest --target cups-server .

# Build Brother variant
docker build -t cups-server:brother --target cups-server-brother .

# Test
docker run -d -p 631:631 cups-server:latest

⁠🩺 Health Checks

The container includes built-in health checks:

# Check container health
docker inspect --format='{{.State.Health.Status}}' cups-server

# View validation logs
docker logs cups-server | grep "Validation Summary"

⁠🐛 Troubleshooting

⁠Printer Not Detected

1. Check USB permissions:

   ls -la /dev/bus/usb/*/*
   # Should show rw-rw-rw- permissions
   

   Copy

2. Verify USB passthrough:

   docker exec cups-server lsusb
   # Should list your printer
   

   Copy

3. Check CUPS backends:

   docker exec cups-server lpinfo -v
   # Should show usb:// devices
   

   Copy

⁠Cannot Access Web Interface

1. Check if CUPS is running:

   docker exec cups-server pgrep cupsd
   

   Copy

2. Verify port binding:

   docker port cups-server
   # Should show 631/tcp -> 0.0.0.0:631
   

   Copy

3. Test connection:

   curl -I http://localhost:631
   

   Copy

⁠Driver Installation Failed

# Check logs
docker logs cups-server | grep "Brother"

# Manual installation
docker exec -it cups-server bash
bash /usr/local/bin/install-brother-printer.sh

⁠🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

⁠📝 License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

⁠🙏 Acknowledgments

• Based on Debian Bookworm
• Uses CUPS⁠ - Common UNIX Printing System
• Brother driver installer from Brother Solutions⁠

⁠📞 Support

• 🐛 Report Issues⁠
• 💬 Discussions⁠

⁠🔗 Links

• Docker Hub⁠
• GitHub Repository⁠