voska/escpos-receipt-printer repository overview

⁠ESC/POS Receipt Printer - Docker Container

A containerized Node.js application for printing TODO tickets and receipts on thermal ESC/POS printers. Supports both USB and network printers

⁠🚀 Quick Start

⁠Network Printer (Recommended)

docker run -d \
  --name todo-printer \
  -p 3000:3000 \
  -e PRINTER_NETWORK_IP=192.168.1.100 \
  -e PRINTER_NETWORK_PORT=9100 \
  voska/escpos-receipt-printer

⁠USB Printer (Linux hosts only)

docker run -d \
  --name todo-printer \
  -p 3000:3000 \
  --privileged \
  -v /dev:/dev \
  -e PRINTER_VENDOR_ID=0x20d1 \
  -e PRINTER_PRODUCT_ID=0x7008 \
  voska/escpos-receipt-printer

⁠📋 Print Your First Ticket

curl -X POST http://localhost:3000/print-todo \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Welcome to containerized printing!",
    "assignee": "Docker User",
    "description": "Successfully set up the thermal printer container"
  }'

⁠🛠️ Configuration

⁠Environment Variables

⁠Supported Printer Types

• EPSON (default)
• STAR
• TANCA
• DRAUMA

⁠🐳 Docker Compose

Create a docker-compose.yml:

services:
  todo-printer:
    image: voska/escpos-receipt-printer
    container_name: todo-printer-server
    ports:
      - "3000:3000"
    environment:
      - PRINTER_VENDOR_ID=${PRINTER_VENDOR_ID}
      - PRINTER_PRODUCT_ID=${PRINTER_PRODUCT_ID}
      - PRINTER_TYPE=${PRINTER_TYPE}
      - PRINTER_NETWORK_IP=${PRINTER_NETWORK_IP}
      - PRINTER_NETWORK_PORT=${PRINTER_NETWORK_PORT:-9100}
      - NODE_ENV=production
    privileged: true # For USB device access
    volumes:
      - /dev:/dev # For USB device access
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped

Create a .env file with your printer settings:

# For network printer
PRINTER_NETWORK_IP=192.168.1.100
PRINTER_NETWORK_PORT=9100

# For USB printer  
PRINTER_VENDOR_ID=0x20d1
PRINTER_PRODUCT_ID=0x7008

# Optional
PRINTER_TYPE=EPSON

Then run: docker-compose up -d

⁠🌐 API Endpoints

⁠POST /print-todo

Print a TODO ticket

Request:

{
  "title": "Fix login bug",
  "assignee": "John Doe",
  "description": "Users cannot login with special characters"
}

⁠GET /health

Check server and printer status.

⁠GET /printer-status

Get detailed printer connection info.

⁠GET /

API documentation.

⁠🔧 Platform Support

⁠✅ Fully Supported

• Linux - Full USB and network support
• Network printers - All platforms (recommended)

⁠⚠️ Limited Support

• macOS/Windows with USB - Use network mode or run natively
• Docker Desktop virtualization prevents USB passthrough

⁠🔍 Troubleshooting

⁠Container Won't Start

# Check logs
docker logs todo-printer

# Test printer connectivity
docker exec todo-printer curl http://localhost:3000/health

⁠USB Printer Not Detected

1. Ensure --privileged and -v /dev:/dev are used
2. Check USB IDs: lsusb on host
3. Verify printer is powered on
4. Consider using network mode instead

⁠Network Printer Connection Issues

1. Verify IP address is reachable from container
2. Check printer network settings
3. Ensure port 9100 (or custom port) is open
4. Test with: telnet PRINTER_IP 9100

⁠📄 Printer Output

The container produces professional-looking tickets with:

• Clear task titles and descriptions
• Assignee information
• Timestamps
• Clean formatting optimized for thermal printers

Perfect for:

• Task management systems
• Issue tracking
• Physical kanban boards
• Deployment notifications

⁠🔗 Links

• GitHub Repository⁠
• API Documentation⁠ (when running)
• ESC/POS Command Reference⁠

Tags: thermal-printer, escpos, receipt-printer, nodejs, docker, api, todo, printing, pos-printer