PrintDash

A self-hosted office printer management dashboard with SNMP-based toner/status monitoring, print job control, network scanning, and Telegram alerts — all from a single Node.js process.

---

Features

Printer Monitoring

• SNMP polling of networked printers (Canon, HP, and others)
• Toner/ink levels per cartridge with low-toner threshold alerts
• Paper tray status and empty tray detection
• Jam, cover-open, and service alert detection
• Online/offline state with consecutive-failure debounce (avoids false alarms from transient SNMP timeouts)
• Page count tracking with history per printer
• Uptime display

Print Management (via CUPS)

• View all CUPS print queues and their current status
• Submit print jobs directly from the dashboard (file upload)
• Live and completed job history with job cancellation
• Pause/resume individual print queues
• Set default printer
• Discover IPP printers on the local network and add them to CUPS in one click

Scanning (via SANE + Samba)

• Detect connected scanners via scanimage
• Trigger scans remotely from the dashboard
• Browse and download completed scan files
• Built-in Samba config helper — generates the /etc/samba/smb.conf snippet so Canon/HP printers can scan-to-folder directly to the server over SMB (\\SERVER_IP\scans)

Printer Discovery

• SNMP subnet scan to auto-discover printers on your network
• Automatic local subnet detection
• IPP/CUPS discovery as an alternative to SNMP
• One-click add from scan results

Alerts (Telegram)

• Instant notifications for low toner, paper empty, jams, offline, and back-online events
• Per-alert type toggles (enable/disable individually)
• Configurable toner threshold percentage
• Alert cooldown to prevent repeated notifications for the same condition
• Alert state persisted to disk — server restarts do not re-fire already-sent alerts
• Test message button to verify your bot token and chat ID

Dashboard & Auth

• Dark-themed responsive web UI
• Role-based login — admin (full access) and user (read-only monitoring)
• Admin user management (add, change password, delete)
• Settings page with live Telegram configuration

---

Requirements

• Node.js 18+
• Network access (SNMP, UDP 161) to your printers
• CUPS installed and running on the host — PrintDash shells out to CUPS command-line tools (lpstat, lp, cancel, lpadmin, lpinfo, cupsenable, cupsdisable) for print queue management, job control, and IPP-based printer discovery
• SANE (scanimage) installed on the host for scanner support
• Samba (smbd) installed on the host if you want scan-to-folder from printer web UIs
• Appropriate printer drivers for your hardware (Canon, HP, etc.) installed via CUPS

On Debian/Ubuntu:

sudo apt update
sudo apt install -y cups cups-client sane-utils samba printer-driver-all

The user running the Node.js process needs permission to run CUPS admin commands:

sudo usermod -aG lpadmin $USER

---

Installation

git clone https://github.com/isuruwa/printdash.git
cd printdash
npm install

---

Configuration

PrintDash stores its runtime data in JSON files that are not included in this repo (gitignored — they contain credentials and your internal network layout). Copy the provided examples to get started:

cp printers.example.json printers.json
cp settings.example.json settings.json

File	Purpose
printers.json	List of printers to monitor (IP, SNMP community string, brand, location)
settings.json	Telegram bot token/chat ID and alert thresholds
users.json	Created automatically on first run with default accounts admin/admin123 and user/user123

Change the default passwords immediately after first login.

Environment variables (optional)

Variable	Default	Purpose
USERS_FILE	./users.json	Path to the users/auth file
DATA_FILE	./printers.json	Path to the printers list
SETTINGS_FILE	./settings.json	Path to the settings file
ALERT_STATE_FILE	./alert-state.json	Persisted alert state (auto-created)
SCAN_DIR	/opt/scans	Directory where scan files are saved
UPLOAD_DIR	/tmp/printdash-uploads	Temp directory for print job uploads

The app listens on port 3003 (edit PORT in server.js to change).

---

Running

npm start

For production, use PM2:

pm2 start server.js --name printdash
pm2 save

---

Scan-to-Folder Setup (optional)

To let your printer scan directly to the server over SMB:

1. Go to Settings → Scans in the dashboard — it generates the exact Samba config block for your server
2. Add the block to /etc/samba/smb.conf and restart: systemctl restart smbd
3. On the printer's web UI set: Scan → Scan to Folder → \\SERVER_IP\scans

---

Security Notes

• Never commit users.json, printers.json, settings.json, or alert-state.json — they contain password hashes, your Telegram bot token, and internal network details. All are excluded via .gitignore.
• Passwords are stored salted and hashed (scrypt), never in plaintext.
• Put this behind a reverse proxy with HTTPS if exposing it outside your LAN.

---

License

MIT