task_receipts/PRINTER_SETUP.md

Printer Setup for Task Receipts

This document explains how to set up the Task Receipts application with USB printer support using Docker.

Prerequisites

• USB thermal printer (ESC/POS compatible)
• Docker and Docker Compose installed
• Linux host system (for USB device access)

Quick Start

1. Run with Printer Support

# Build and start with printer support
docker-compose -f docker-compose.printer.yml up --build

# Or run in background
docker-compose -f docker-compose.printer.yml up -d --build

Configuration Options

Environment Variables

Variable	Description	Example
PRINTER_DRIVER	Type of printer connection	serial

USB Device Mounting

The printer configuration includes several USB mounting options:

volumes:
  # Mount specific USB bus
  - /dev/bus/usb:/dev/bus/usb:rw

devices:
  # Mount USB devices specifically
  - /dev/bus/usb:/dev/bus/usb

privileged: true  # Required for USB access

Troubleshooting

Printer Not Found

1. Check USB device listing:

   lsusb
   

2. Verify device permissions:

   ls -la /dev/bus/usb/
   

3. Check container logs:

   docker-compose -f docker-compose.printer.yml logs server
   

Permission Issues

If you encounter permission issues:

1. Add your user to the docker group:

   sudo usermod -aG docker $USER
   

2. Restart Docker service:

   sudo systemctl restart docker
   

3. Log out and back in for group changes to take effect.

Alternative: Run with sudo

If you still have issues, you can run with elevated privileges:

sudo docker-compose -f docker-compose.printer.yml up --build

Common Printer Models

ESC/POS Compatible Printers

Most thermal printers support ESC/POS commands. Common models include:

• Star TSP100 series
• Epson TM-T88 series
• Citizen CT-S310 series
• Generic thermal printers

Finding Your Printer's IDs

# Method 1: lsusb
lsusb

# Method 2: dmesg (after plugging in printer)
dmesg | tail -20

# Method 3: udevadm
udevadm info -a -n /dev/usb/lp0

Security Considerations

⚠️ Warning: The printer configuration uses privileged: true which gives the container elevated privileges. This is necessary for USB device access but should be used carefully in production environments.

Alternative Security Approaches

1. Use specific device capabilities:

   cap_add:
     - SYS_RAWIO
   

2. Mount only specific devices:

   devices:
     - /dev/usb/lp0:/dev/usb/lp0
   

3. Use udev rules to set proper permissions on the host.

Testing Printer Connection

Once the container is running, you can test the printer connection:

1. Check if printer is detected:

   docker exec -it task-receipts-server lsusb
   

2. Test printer from the application:

   • Use the web interface to send a test print
   • Check the server logs for printer-related messages

Stopping the Services

# Stop all services
docker-compose -f docker-compose.printer.yml down

# Stop and remove volumes
docker-compose -f docker-compose.printer.yml down -v

Support

For printer-specific issues:

1. Check the server logs for detailed error messages
2. Verify your printer is ESC/POS compatible
3. Ensure the USB IDs are correctly configured
4. Test the printer on the host system first

For Docker-related issues, refer to the main DOCKER.md documentation.