Home Assistant CUPS Print Server App

This Home Assistant app provides a CUPS (Common Unix Printing System) print server, allowing you to manage and share printers over your local network. It's designed for Home Assistant users who want to integrate network printing capabilities directly into their smart home setup.

Features

• Network Printing: Share printers across your local network using CUPS
• Web Interface: Access the CUPS administration panel at http://<your-ha-ip>:631 to add and manage printers
• Secure Administration: Configurable authentication for the CUPS admin interface
• Printer Support: Compatible with a wide range of network and USB printers
• Lightweight: Built on Alpine Linux for minimal resource usage
• Data Persistence: Printer settings and configurations persist across restarts and updates

Installation

From Home Assistant App Store

1. Navigate to your Home Assistant instance.
2. Go to Settings → Apps → Install App.
3. Click the 3-dot menu in the top right corner and select Repositories.
4. Add https://github.com/arest/cups-addon as a repository.
5. Find the "CUPS Print Server" app in the store and click it.
6. Click Install.

Manual Installation

If you prefer to manually install:

1. Clone this repository to your local machine:

   git clone https://github.com/arest/cups-addon.git

2. Copy the repository to your Home Assistant add-ons directory:

   scp -r cups-addon/cups root@<your-ha-ip>:/addons/

3. In Home Assistant, go to Settings → Apps → Install App.

4. Click the 3-dot menu (top right) → Repositories.

5. Add /addons as a repository URL and click Add.

6. Refresh the app store to see "CUPS Print Server."

7. Install the app.

Configuration

The app provides the following configuration options:

admin_username: printadmin
admin_password: your_secure_password

• admin_username: Username for the CUPS admin interface (default: admin)
• admin_password: Password for the CUPS admin interface

Both values are applied when the app starts. If admin_password is non-empty (the shipped default is admin), opening the Administration pages or adding, modifying, or deleting printers prompts for these credentials. Printing and cancelling jobs remain available to LAN clients without a login.

Set a strong password before exposing the app to your network. Leave admin_password empty to disable admin authentication.

The add-on owns only the block between the # >>> CUPS ADD-ON MANAGED CONFIG and # <<< CUPS ADD-ON MANAGED CONFIG <<< markers in /share/cups/config/cupsd.conf. It is regenerated on every start so changes to the app options take effect. Add custom directives (for example ServerAlias *) outside that block; they are preserved across app restarts and updates, including when you save the file from the CUPS web UI.

After configuring:

1. Start the app from the Info tab.
2. Check the Log tab to ensure it starts successfully.
3. Access the CUPS web interface at http://<your-ha-ip>:631.

Usage

Access the Web Interface

Visit http://<your-ha-ip>:631 in your browser.

Add a Printer

1. Go to the Administration tab.
2. Click Add Printer and follow the prompts.
3. Select the appropriate driver for your printer model.

Print from Devices

Shared printers are advertised on the LAN via AirPrint/Bonjour (Avahi). On iPhone, iPad, and Mac they should appear as nearby printers. Do not pick the printer's own LPD advertisement (for example "Canon MG5200 series") — that bypasses this server.

To add the CUPS queue manually on macOS:

1. System Settings → Printers & Scanners → Add Printer → IP
2. Address: <your-ha-hostname> (e.g. homeassistant.local)
3. Protocol: IPP
4. Queue: printers/<queue-name>
5. Use: Auto Select

You can also print to ipp://<your-ha-ip>:631/printers/<queue-name>.

Supported Printer Types

This app supports various printer types:

• Network printers (via IPP, LPD, etc.)
• USB printers connected to your Home Assistant host
• Shared Windows printers (via Samba)
• AirPrint for Apple devices

Troubleshooting

Can't Access Web Interface

• Ensure the app is running (check logs).
• Verify port 631 isn't blocked by your firewall.
• Check that your network allows access to the Home Assistant device.

Printer Not Detected

• Ensure the printer is network-accessible or connected via USB to the host.
• For USB printers, you may need to configure USB device pass-through to the app.
• Check CUPS logs in the app's Log tab.

Printer Drivers

Gutenprint CUPS drivers (Canon, HP, Brother, and many others) are bundled via the Alpine gutenprint-cups package. In the add-printer list, models often appear as a series name (for example Canon PIXMA MG5250 is Canon MG5200 series - CUPS+Gutenprint).

Brother host-based (GDI) lasers that speak neither PCL nor PostScript (for example HL-2130, HL-2140, HL-1110, DCP-7030/7055) are covered by the bundled open-source brlaser driver: pick Brother , using brlaser.

For printers Gutenprint does not cover, supply a .deb through printer_driver_deb (place the file in /share) or use a PPD from:

• https://www.openprinting.org/download/PPD/
• https://www.openprinting.org/drivers/

Authentication Issues

• Verify you're using the correct username and password configured in the app settings.
• Changing the username or password requires an app restart; the credentials are applied during startup.
• Authentication is requested for administration pages and printer management, not for the public status pages or for submitting/cancelling print jobs.
• If you've forgotten your password, set a new one in the app configuration and restart the app.
• Custom cupsd.conf directives are persistent when placed outside the managed block. Only the block between the CUPS ADD-ON MANAGED CONFIG markers is rewritten on restart.

Contributing

Contributions are welcome! Please:

1. Fork this repository.
2. Create a feature branch (git checkout -b feature/your-feature).
3. Commit your changes (git commit -m "Add your feature").
4. Push to the branch (git push origin feature/your-feature).
5. Open a pull request.

Running the checks locally

.github/workflows/ci.yml validates the add-on metadata, lints the init scripts, then builds and smoke-tests the image. Run the same checks before opening a PR:

# Add-on metadata: required keys, known arch values, options/schema and
# ports/description symmetry, version vs CHANGELOG, slug vs directory name
pip install pyyaml
python3 .github/scripts/validate_addon.py

# Init scripts
bash -n cups/rootfs/etc/cont-init.d/*
shellcheck --severity=error -s bash cups/rootfs/etc/cont-init.d/*

# Build and smoke test
docker build -t cups-addon:ci cups/
.github/scripts/smoke_test.sh cups-addon:ci

The smoke test boots the image the way the Supervisor does and checks that cupsd comes up, that the compiled filters (rastertokpsl, raster2dymolw/m) and vendored PPDs are present, that avahi is advertising for AirPrint, that the cupsd.conf access policy still covers the LAN ranges, and that a LAN client can reach the web UI.

Any change to cups/config.yaml must bump version to match the newest ## [x.y.z] heading in CHANGELOG.md — CI enforces this.

License

This project is licensed under the MIT License.

Credits

• Built by Andrea Restello
• Powered by Home Assistant and CUPS

Data Persistence

This app stores all CUPS data in the Home Assistant /share directory, ensuring:

• Printer configurations persist across app restarts
• Custom cupsd.conf directives outside the managed block survive restarts
• Print jobs and settings are maintained through system reboots
• App updates won't cause loss of printer configurations
• All CUPS data is included in Home Assistant backups

The following directories are maintained in the persistent storage:

• /share/cups/config: CUPS configuration files
• /share/cups/cache: CUPS cache data
• /share/cups/logs: CUPS log files
• /share/cups/state: CUPS state information