Print Gateway

A lightweight daemon that runs on a workstation physically connected to printers (USB or LAN), bridging them to the cloud print service via outbound WebSocket. Part of the Glico Healthcare microservice ecosystem.

How It Works

The gateway lives on the machine that has the printers attached. It connects outbound to the print server over WebSocket (no open inbound ports needed), receives print commands, executes them via the OS spooler (CUPS on macOS/Linux, .NET System.Printing on Windows), and streams status updates back.

Installation

From source

git clone <repo-url>
npm install

Config lives at the project root (.env, config/printers.json).

Global CLI

npm install -g @glicogh/print-gateway

Config lives at ~/.config/@glicogh/print-gateway/ (overridable via PRINT_GATEWAY_CONFIG_DIR).

Windows: SumatraPDF is required for printing document formats (PDF, PS, XPS, images). Run print-gateway install-sumatra (or npm run install-sumatra in dev) to auto-download the latest version; the setup wizard will also offer to install it.

Setup

Run the interactive wizard:

# From source
npm run setup

# Global install
print-gateway setup

This generates .env and config/printers.json. The gateway refuses to start without them. On Windows, setup also checks for SumatraPDF and offers to install it.

Running

Development (source only)

npm run dev

Hot-reload via tsx watch.

Direct

# From source
npm run build && node dist/src/index.js

# Global install
print-gateway start

With PM2 (process manager)

# From source
npm run build && npm run start:pm2

# Global install
pm2 start $(npm root -g)/@glicogh/print-gateway/dist/src/index.js --name "print-gateway"

Auto-start on boot

After starting the gateway with PM2 and verifying it works, save the process list and register auto-start:

pm2 save

# macOS / Linux
pm2 startup

# Windows (run as Administrator)
print-gateway install-pm2-boot

Windows: pm2 startup is not supported. print-gateway install-pm2-boot creates a scheduled task that runs pm2 resurrect at system startup as SYSTEM. Run it once as Administrator after pm2 save.

Features

• WebSocket client — connects to the print server as a client, auto-reconnects on disconnect
• Printer state broadcast — sends an immediate heartbeat on connection open, then periodic heartbeats to sync printer list
• Cross-platform — works on Windows (.NET System.Printing) and macOS/Linux (CUPS lp)
• Progress tracking — polls the OS spooler and streams status back via WebSocket
• Page selection — print a specific page from a multi-page document via the page option (uses -o page-ranges=N on CUPS, PageMediaRange on Windows)
• Authentication — auth and account selection via HTTP headers (Authorization, X-Account-Id, X-Gateway-Name) at WebSocket handshake
• Interactive setup — npm run setup wizard configures .env and printers; remembers previous selections on re-run

Documentation

• docs/PROTOCOL.md — WebSocket protocol reference (messages, fields, error handling).
• docs/IMPLEMENTATION.md — architecture, print options, status tracking details.