diff --git a/PRINTER_SETUP.md b/PRINTER_SETUP.md new file mode 100644 index 0000000..1fee42d --- /dev/null +++ b/PRINTER_SETUP.md @@ -0,0 +1,166 @@ +# 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. \ No newline at end of file diff --git a/docker-compose.printer.yml b/docker-compose.printer.yml new file mode 100644 index 0000000..e10b2f7 --- /dev/null +++ b/docker-compose.printer.yml @@ -0,0 +1,54 @@ +version: '3.8' + +services: + server: + build: + context: . + dockerfile: server/Dockerfile + container_name: task-receipts-server + ports: + - "4000:4000" + environment: + - NODE_ENV=production + # Printer configuration + - PRINTER_DRIVER=serial + volumes: + # Mount database directory for persistence + - ./server/data/prod.sqlite3:/app/server/prod.sqlite3:rw + # Mount USB devices for printer access + # /dev/bus/usb:/dev/bus/usb:rw + devices: + # Mount USB devices specifically + - /dev/bus/usb:/dev/bus/usb + privileged: true # Required for USB device access + restart: unless-stopped + healthcheck: + test: ["CMD", "node", "-e", "require('http').get('http://localhost:4000/graphql', (res) => { process.exit(res.statusCode === 200 ? 0 : 1) })"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 40s + networks: + - task-receipts-network + + client: + build: + context: . + dockerfile: client/Dockerfile + container_name: task-receipts-client + ports: + - "80:80" + depends_on: + server: + condition: service_healthy + restart: unless-stopped + networks: + - task-receipts-network + +networks: + task-receipts-network: + driver: bridge + +volumes: + server-data: + driver: local \ No newline at end of file diff --git a/server/Dockerfile b/server/Dockerfile index ac1703b..71018f8 100644 --- a/server/Dockerfile +++ b/server/Dockerfile @@ -37,4 +37,4 @@ EXPOSE 4000 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ CMD node -e "require('http').get('http://localhost:4000/graphql', (res) => { process.exit(res.statusCode === 200 ? 0 : 1) })" ENTRYPOINT ["dumb-init", "--"] -CMD ["node", "dist/index.js"] \ No newline at end of file +CMD ["node", "dist/server/src/index.js"] \ No newline at end of file