kaoshonen/receipty

Receipt Printer Control Web App

A lightweight web UI and API to send plain-text jobs to an Epson TM-T88IV receipt printer over USB or Ethernet. Includes job logging, status checks, and Docker-first setup.

Features

• Immediate print submit with queued job ids
• Printer status checks and readiness endpoints
• SQLite-backed job audit trail with error stacks
• Reprint previous jobs from the Activity log
• USB device path override and Ethernet RAW TCP
• Docker Compose profiles for usb and ethernet

Quick Start (Local)

bash
npm install
npm run dev

Create .env from the example below and run the server. By default it ***ds to 127.0.0.1:3000.

Docker Compose

Profiles are required for usb/ethernet. If you omit --profile, Compose will report "no service selected".

bash
docker compose --profile ethernet up --build

For USB, ensure device mappings match your host:

bash
docker compose --profile usb up --build

Docker Hub (remote servers)

Use the published image instead of build: .:

bash
docker compose --profile ethernet pull
docker compose --profile ethernet up -d

If the container fails with SQLITE_CANTOPEN, ensure the data volume is writable:

bash
docker compose --profile ethernet run --rm --user root receipty-ethernet \
  sh -c "mkdir -p /app/data && chown -R node:node /app/data"

Configuration

Config is driven by environment variables and an optional JSON file.

• Optional file: set CONFIG_PATH=/config/receipty.json and mount it into the container.
• Environment variables override values from the file.

Environment variables

USB mode variables

Ethernet mode variables

API

• POST /api/print { "text": "..." }
• POST /api/jobs/:id/reprint
• GET /api/status
• GET /api/jobs?page=1&pageSize=20
• GET /healthz
• GET /readyz

If APP_HOST is not localhost, include X-API-Key in API requests.

Development

bash
npm run test
npm run build
npm start

Notes

• USB printing uses escpos-usb by default and will fall back to writing the raw payload to USB_DEVICE_PATH when provided.
• Ethernet printing uses raw TCP with timeouts and retry jitter.
• If USB access fails, try mapping /dev/bus/usb first; only use privileged: true as a last resort.