166 lines
3.5 KiB
Markdown
166 lines
3.5 KiB
Markdown
# 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. |