# 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

```bash
# 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:

```yaml
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:**
   ```bash
   lsusb
   ```

2. **Verify device permissions:**
   ```bash
   ls -la /dev/bus/usb/
   ```

3. **Check container logs:**
   ```bash
   docker-compose -f docker-compose.printer.yml logs server
   ```

### Permission Issues

If you encounter permission issues:

1. **Add your user to the docker group:**
   ```bash
   sudo usermod -aG docker $USER
   ```

2. **Restart Docker service:**
   ```bash
   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:

```bash
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

```bash
# 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:**
   ```yaml
   cap_add:
     - SYS_RAWIO
   ```

2. **Mount only specific devices:**
   ```yaml
   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:**
   ```bash
   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

```bash
# 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.