Installation des Order Printers

Diese Anleitung führt Sie durch die Installation und Einrichtung des ShopBite Order Printers.

Voraussetzungen prüfen

Bevor Sie mit der Installation beginnen, stellen Sie sicher, dass alle Voraussetzungen erfüllt sind:

Server-Voraussetzungen

# PHP-Version prüfen
php -v
# Sollte PHP 8.2 oder höher anzeigen

# Composer installieren (falls nicht vorhanden)
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"

# SQLite-Erweiterung prüfen
php -m | grep sqlite

Drucker-Voraussetzungen

Der Order Printer sendet ESC/POS direkt an den Drucker; CUPS wird nicht benötigt. Sie brauchen eine der folgenden Varianten:

• einen USB- oder seriellen Bondrucker an dem Rechner, auf dem der Order Printer läuft. Er erscheint als Gerätedatei wie /dev/usb/lp0; der Benutzer des Dienstes braucht Schreibrechte darauf (Debian/Ubuntu: sudo usermod -aG lp <benutzer>).
• einen Netzwerkdrucker (oder einen Raspberry Pi als Drucker-Gateway), der über TCP-Port 9100 (Raw-ESC/POS) erreichbar ist.

Installation

1. Repository klonen

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

2. Abhängigkeiten installieren

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

Für Entwicklungszwecke:

composer install

3. Umgebung konfigurieren

Kopieren Sie die Beispiel-Umgebungsdatei:

cp .env .env.local

4. Datenbank einrichten

# Datenbank erstellen
bin/console doctrine:database:create

# Schema aktualisieren
bin/console doctrine:schema:update --force

Shopware 6 Integration

API-Zugang einrichten

1. Shopware Administration öffnen
2. Einstellungen > System > Integrationen
3. Neue Integration hinzufügen
4. Berechtigungen setzen:
   • order:read - Bestellungen lesen
   • order:update - Bestellstatus aktualisieren
   • customer:read - Kundendaten lesen

Integration konfigurieren

Bearbeiten Sie die .env.local-Datei:

# Shopware API-Zugang
SHOPWARE_HOST=https://ihre-shopware-domain.de
SHOPWARE_CLIENT_ID=ihre_client_id
SHOPWARE_CLIENT_SECRET=ihre_client_secret

# Druckeranbindung (siehe "Drucker einrichten" unten)
PRINTER_DSN=file:///dev/usb/lp0

# Datenverzeichnis
DATA_DIR="/data/receipts/"

Drucker einrichten

Der Drucker wird über die Variable PRINTER_DSN in .env.local ausgewählt:

Verbindungen zu tcp://-Druckern laufen nach 5 Sekunden in einen Timeout; ein nicht erreichbarer Drucker lässt den Druckauftrag fehlschlagen, statt den Worker zu blockieren.

Verbindung ohne Shopware und ohne echte Bestellung prüfen:

bin/console printer:check   # nur Erreichbarkeit, druckt nichts, Exit-Code 0/1 (auch als Docker-Healthcheck nutzbar)
bin/console printer:test    # druckt einen Testbon mit Restaurantname, Uhrzeit, Hostname und Drucker-DSN

Beide akzeptieren --dsn=tcp://…, um einen anderen als den konfigurierten Drucker zu testen. Setzen Sie SHOP_NAME in .env.local, damit Ihr Restaurantname auf dem Testbon erscheint; sonst wird die Domain aus SHOPWARE_HOST verwendet.

Dienst starten

Entwicklungsmodus

# Scheduler starten (prüft alle 10 Sekunden auf neue Bestellungen)
bun run scheduler

# Worker starten (verarbeitet Druckaufträge)
bun run worker

Docker (empfohlen für Dokploy)

Das Repository enthält ein Dockerfile und eine Referenz-compose.yaml, die beide Worker unter Supervisor in einem Container betreiben, mit einem Healthcheck, der die Druckerverbindung prüft. Die Konfiguration erfolgt vollständig über Umgebungsvariablen, die SQLite-Warteschlange und die Bon-Kopien liegen auf dem Volume /app/data:

APP_SECRET=$(openssl rand -hex 16) \
SHOPWARE_HOST=https://ihre-shopware-domain.de \
SHOPWARE_CLIENT_ID=ihre_client_id \
SHOPWARE_CLIENT_SECRET=ihre_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

Auf Dokploy legen Sie einen Compose-Dienst aus dem Repository an, tragen dieselben Variablen im Reiter Environment ein und deployen; Dokploy baut das Image selbst. Für einen USB-Drucker am Docker-Host mappen Sie das Gerät (devices: - /dev/usb/lp0:/dev/usb/lp0) und fügen die lp-Gruppe des Hosts hinzu (group_add). Details: docs/docker.md im Repository.

Produktionsmodus

Für den Produktionsbetrieb empfehlen wir die Verwendung von Supervisor:

1. Supervisor-Konfiguration erstellen (/etc/supervisor/conf.d/order-printer.conf):

[program:order-printer-scheduler]
command=/pfad/zum/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=/pfad/zum/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. Supervisor aktualisieren:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start all

Erste Schritte

Testbestellung erstellen

1. In Shopware eine Testbestellung erstellen
2. Bestellstatus auf "Offen" setzen
3. Drucker beobachten - Der Bon sollte automatisch gedruckt werden

Logs überprüfen

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

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

Häufige Installationsprobleme

Problem: Es wird nichts gedruckt

• Lösung: PRINTER_DSN in .env.local prüfen, dann bin/console printer:check (Erreichbarkeit) und bin/console printer:test (Testbon) ausführen; beide erklären, was nicht stimmt
• Lösung (USB): prüfen, ob das Gerät existiert (ls -l /dev/usb/lp*) und der Dienstbenutzer darauf schreiben darf (sudo usermod -aG lp <benutzer>, danach neu anmelden)
• Lösung (Netzwerk): prüfen, ob Port 9100 erreichbar ist (nc -vz 192.168.1.100 9100); ein nicht erreichbarer Drucker schlägt nach 5 Sekunden mit Cannot connect to printer fehl
• Lösung: Die Bon-Kopie in DATA_DIR zeigt, ob die Bestellung überhaupt verarbeitet wurde

Problem: Verbindung zur Shopware API fehlgeschlagen

• Lösung: API-Zugangsdaten in .env.local prüfen
• Lösung: Firewall-Einstellungen überprüfen
• Lösung: Shopware-Logs auf API-Fehler prüfen

Problem: Datenbankfehler

• Lösung: SQLite-Berechtigungen prüfen: chmod 666 data/queue_*.db
• Lösung: Datenbank neu erstellen: rm data/queue_*.db && bin/console doctrine:database:create

Nächste Schritte

• Konfiguration
• Betrieb und Wartung
• Fehlerbehebung