Installation of the Order Printer

This guide will walk you through the installation and setup of the ShopBite Order Printer.

Check Prerequisites

Before you begin the installation, make sure all prerequisites are met:

Server Prerequisites

# Check PHP version
php -v
# Should show PHP 8.2 or higher

# Install Composer (if not present)
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"

# Check SQLite extension
php -m | grep sqlite

Printer Prerequisites

The Order Printer sends ESC/POS directly to the printer; CUPS is not required. You need one of:

• a USB or serial thermal printer attached to the machine running the Order Printer. It appears as a device file such as /dev/usb/lp0; the user running the service needs write access to it (Debian/Ubuntu: sudo usermod -aG lp <user>).
• a network printer (or a Raspberry Pi acting as a printer gateway) reachable on TCP port 9100 (raw ESC/POS).

Installation

1. Clone Repository

git clone https://github.com/shopbite/order-printer.git
cd order-printer

2. Install Dependencies

composer install --no-dev --optimize-autoloader

For development purposes:

composer install

3. Configure Environment

Copy the example environment file:

cp .env .env.local

4. Set Up Database

# Create database
bin/console doctrine:database:create

# Update schema
bin/console doctrine:schema:update --force

Shopware 6 Integration

Set Up API Access

1. Open Shopware Administration
2. Settings > System > Integrations
3. Add New Integration
4. Set Permissions:
   • order:read - Read orders
   • order:update - Update order status
   • customer:read - Read customer data

Configure Integration

Edit the .env.local file:

# Shopware API Access
SHOPWARE_HOST=https://your-shopware-domain.de
SHOPWARE_CLIENT_ID=your_client_id
SHOPWARE_CLIENT_SECRET=your_client_secret

# Printer connection (see "Set Up Printer" below)
PRINTER_DSN=file:///dev/usb/lp0

# Data Directory
DATA_DIR="/data/receipts/"

Set Up Printer

The printer is selected with the PRINTER_DSN variable in .env.local:

Connections to tcp:// printers time out after 5 seconds, so an unreachable printer fails the print job instead of blocking the worker.

Check the connection without Shopware and without a real order:

bin/console printer:check   # reachability only, prints nothing, exit code 0/1 (also usable as Docker health check)
bin/console printer:test    # prints a test receipt with shop name, time, hostname and printer DSN

Both accept --dsn=tcp://… to try another printer than the configured one. Set SHOP_NAME in .env.local to print your restaurant name on the test receipt; otherwise the SHOPWARE_HOST domain is used.

Start Service

Development Mode

# Start scheduler (checks every 10 seconds for new orders)
bun run scheduler

# Start worker (processes print jobs)
bun run worker

Docker (recommended for Dokploy)

The repository ships a Dockerfile and a reference compose.yaml that run both workers under supervisor in one container, with a health check that verifies the printer connection. Configuration is done entirely through environment variables, the SQLite queue and the receipt copies live on the /app/data volume:

APP_SECRET=$(openssl rand -hex 16) \
SHOPWARE_HOST=https://your-shopware-domain.de \
SHOPWARE_CLIENT_ID=your_client_id \
SHOPWARE_CLIENT_SECRET=your_client_secret \
PRINTER_DSN=tcp://192.168.1.100:9100 \
docker compose up -d

docker compose logs -f
docker compose exec order-printer su-exec app php bin/console printer:test

On Dokploy create a Compose service from the repository, set the same variables in its Environment tab and deploy; Dokploy builds the image itself. For a USB printer attached to the Docker host map the device (devices: - /dev/usb/lp0:/dev/usb/lp0) and add the host's lp group (group_add). Details: docs/docker.md in the repository.

Production Mode

For production operation, we recommend using Supervisor:

1. Create Supervisor Configuration (/etc/supervisor/conf.d/order-printer.conf):

[program:order-printer-scheduler]
command=/path/to/project/bin/console messenger:consume scheduler_default
user=www-data
autostart=true
autorestart=true
stderr_logfile=/var/log/order-printer-scheduler.err.log
stdout_logfile=/var/log/order-printer-scheduler.out.log

[program:order-printer-worker]
command=/path/to/project/bin/console messenger:consume async
user=www-data
autostart=true
autorestart=true
stderr_logfile=/var/log/order-printer-worker.err.log
stdout_logfile=/var/log/order-printer-worker.out.log

2. Update Supervisor:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start all

Getting Started

Create Test Order

1. Create a test order in Shopware
2. Set order status to "Open"
3. Monitor printer - The receipt should be printed automatically

Check Logs

# Scheduler logs
tail -f /var/log/order-printer-scheduler.out.log

# Worker logs
tail -f /var/log/order-printer-worker.out.log

Common Installation Issues

Problem: Nothing is printed

• Solution: Check PRINTER_DSN in .env.local, then run bin/console printer:check (reachability) and bin/console printer:test (test receipt); both explain what is wrong
• Solution (USB): make sure the device exists (ls -l /dev/usb/lp*) and the service user can write to it (sudo usermod -aG lp <user>, then log in again)
• Solution (network): make sure port 9100 is reachable (nc -vz 192.168.1.100 9100); an unreachable printer fails after 5 seconds with Cannot connect to printer
• Solution: the receipt copy in DATA_DIR shows whether the order was processed at all

Problem: Connection to Shopware API failed

• Solution: Check API credentials in .env.local
• Solution: Check firewall settings
• Solution: Check Shopware logs for API errors

Problem: Database error

• Solution: Check SQLite permissions: chmod 666 data/queue_*.db
• Solution: Recreate database: rm data/queue_*.db && bin/console doctrine:database:create

Next Steps

• Configuration
• Operation and Maintenance
• Troubleshooting