HowTo: ESC/POS NetPrinter mit Docker auf Linux und Hyper-V umsetzen

Dieses HowTo zeigt, wie du das Projekt gilbertfl/escpos-netprinter als virtuellen ESC/POS-Netzwerkdrucker einsetzt. Der Dienst emuliert einen 80-mm-Bondrucker, nimmt Druckdaten per Netzwerk entgegen und speichert Ausdrucke als HTML-Seiten, die du über eine Weboberfläche ansehen kannst.

Ziel dieser Anleitung: Du richtest escpos-netprinter reproduzierbar auf Linux oder in einer Hyper-V-Umgebung ein, verstehst die benötigten Ports und Datenpfade und kannst Testdrucke sowie Fehlersuche sauber durchführen.

1. Projektüberblick

Das Repository stellt einen containerbasierten ESC/POS-Netzwerkdrucker bereit. Ausdrucke werden nicht auf Papier ausgegeben, sondern als HTML-Belege gespeichert und im Browser angezeigt.

Komponente	Funktion
`9100/tcp`	JetDirect bzw. RAW-Druckdaten für viele POS- und Bondrucker-Clients
`515/tcp`	LPD-Schnittstelle
`80/tcp`	Weboberfläche zum Anzeigen der empfangenen Belege
`631/tcp`	Optional für CUPS-Administration bei Debugging

Wichtig: Laut Projektbeschreibung soll der Container nicht in einem öffentlichen Netzwerk exponiert werden. Zusätzlich ist ein einzelner Druckauftrag standardmäßig auf etwa 10 Sekunden begrenzt. Nutze den Dienst daher nur intern, etwa in einem Labor, Testnetz oder in einer isolierten VM.

2. Voraussetzungen

Ein System mit Docker
Netzwerkzugriff zwischen deinem Testsystem und dem Container
Ein Client oder Testskript, das an Port 9100 oder 515 senden kann
Optional ein persistenter Speicherort für Belege

Für Linux empfiehlt sich Docker Engine. Auf Windows-Hosts mit Hyper-V hast du in der Praxis zwei sinnvolle Wege:

Eine Linux-VM unter Hyper-V, in der Docker Engine läuft
Docker Desktop auf Windows mit Linux-Containern, WSL-2-Backend oder Hyper-V-basierter Virtualisierung

3. Ubuntu Server 22.x vorbereiten und statische IP konfigurieren

Wenn du den ESC/POS-Emulator auf einem dedizierten Ubuntu Server 22.x betreiben willst, solltest du zuerst die Netzwerkkonfiguration sauber festlegen. In diesem Beispiel erhält der Server die statische Adresse 192.168.10.20/24, als Gateway 192.168.10.1 und als DNS-Server ebenfalls 192.168.10.1.

Zielkonfiguration: Ubuntu Server mit fester IP 192.168.10.20/24, damit POS-Clients, Testsysteme oder Hyper-V-Hosts den Emulator immer unter derselben Adresse erreichen können.

3.1 Netzwerknamen prüfen

Prüfe zuerst den Namen des Netzwerkinterfaces. Je nach Installation heißt es häufig eth0, ens160, enp0s3 oder ähnlich.

ip a

3.2 Netplan-Datei bearbeiten

Unter Ubuntu Server 22.x wird die Netzwerkkonfiguration in der Regel mit Netplan verwaltet. Öffne die vorhandene YAML-Datei, zum Beispiel:

sudo nano /etc/netplan/00-installer-config.yaml

Ersetze den Inhalt durch eine Konfiguration wie im folgenden Beispiel. Passe dabei den Interfacenamen an dein System an. Im Beispiel wird eth0 verwendet.

network:
  version: 2
  ethernets:
    eth0:
      dhcp4: no
      addresses:
        - 192.168.10.20/24
      routes:
        - to: default
          via: 192.168.10.1
      nameservers:
        addresses:
          - 192.168.10.1

Wichtig: Achte bei YAML exakt auf Einrückungen mit Leerzeichen. Schon ein kleiner Einrückungsfehler kann dazu führen, dass die Netzwerkkonfiguration nicht übernommen wird.

3.3 Konfiguration testen und anwenden

Teste die Konfiguration zuerst, bevor du sie dauerhaft aktivierst:

sudo netplan try

Wenn alles funktioniert, übernimm die Einstellungen dauerhaft:

sudo netplan apply

3.4 Netzwerkkonfiguration prüfen

ip a
ip route
resolvectl status

Prüfe anschließend die Erreichbarkeit von Gateway und DNS:

ping -c 4 192.168.10.1
ping -c 4 google.com

Erfolgskontrolle: Wenn 192.168.10.20 gesetzt ist, die Standardroute auf 192.168.10.1 zeigt und Namensauflösung funktioniert, ist die Basis für Docker und den ESC/POS-Dienst bereit.

4. Docker auf Ubuntu Server 22.x installieren und konfigurieren

Nach der Netzwerkkonfiguration installierst du Docker Engine direkt auf dem Ubuntu Server. Damit läuft der Emulator stabil und unabhängig von einer Desktop-Umgebung.

4.1 Paketquellen aktualisieren

sudo apt update
sudo apt upgrade -y

4.2 Benötigte Pakete installieren

sudo apt install -y ca-certificates curl gnupg

4.3 Docker-GPG-Schlüssel hinterlegen

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

4.4 Docker-Repository einbinden

echo   "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu   $(. /etc/os-release && echo $VERSION_CODENAME) stable" |   sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

4.5 Docker Engine installieren

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

4.6 Docker-Dienst aktivieren und prüfen

sudo systemctl enable docker
sudo systemctl start docker
sudo systemctl status docker

4.7 Funktionstest mit Docker

sudo docker run hello-world

4.8 Optional: aktuellen Benutzer zur Docker-Gruppe hinzufügen

Wenn du Docker später ohne sudo nutzen möchtest:

sudo usermod -aG docker $USER
newgrp docker

Hinweis: Auf Servern ist der Betrieb mit sudo oft völlig ausreichend. Für Labor- oder Testsysteme ist die Docker-Gruppe bequem, auf produktionsnahen Systemen solltest du Berechtigungen bewusst vergeben.

5. Linux-Umsetzung mit Docker

3.1 Docker auf Linux bereitstellen

Installiere auf einer unterstützten Linux-Distribution Docker Engine. Auf Ubuntu kannst du dafür die offizielle Docker-Dokumentation verwenden.

Empfehlung: Für einen stabilen Testbetrieb ist eine kleine Ubuntu-Server-VM oft die sauberste Lösung. So bleibt dein ESC/POS-Labor getrennt vom Host und lässt sich leicht sichern, klonen oder zurücksetzen.

3.2 Container mit persistentem Speicher starten

Der einfachste Start erfolgt mit dem vorgebauten Image aus Docker Hub. Das Repository nennt dazu folgenden Startansatz:

docker run -d \
  --name escpos-netprinter \
  -p 515:515/tcp \
  -p 80:80/tcp \
  -p 9100:9100/tcp \
  --mount source=receiptVolume,target=/home/escpos-emu/web \
  gilbertfl/escpos-netprinter:3.2

Wenn du statt eines Docker-Volumes lieber ein Host-Verzeichnis verwenden willst, kannst du einen Bind-Mount nutzen:

mkdir -p /srv/escpos-netprinter/web

docker run -d \
  --name escpos-netprinter \
  -p 515:515/tcp \
  -p 80:80/tcp \
  -p 9100:9100/tcp \
  -v /srv/escpos-netprinter/web:/home/escpos-emu/web \
  gilbertfl/escpos-netprinter:3.2

3.3 Weboberfläche aufrufen

Nach dem Start erreichst du die Oberfläche über die zuvor konfigurierte statische Server-IP. In diesem Beispiel lautet die Adresse:

http://192.168.10.20/

Dort erscheinen die empfangenen Belege als HTML-Ausgaben.

6. Umsetzung in Hyper-V

4.1 Empfohlene Variante: Linux-VM in Hyper-V

Die robusteste Umsetzung in Hyper-V ist eine eigene Linux-VM, zum Beispiel Ubuntu Server. Der Hyper-V-Host stellt dabei nur die Virtualisierung bereit, und der ESC/POS-Dienst läuft vollständig in der Gast-VM.

Erstelle in Hyper-V eine neue VM
Verbinde die VM mit einem Externen virtuellen Switch, damit andere Systeme die Druckports erreichen können
Installiere Ubuntu Server
Installiere Docker Engine in der VM
Starte den Container wie im Linux-Abschnitt beschrieben

Warum diese Variante sinnvoll ist: Du erhältst eine klar getrennte Netzwerkschicht, kannst Snapshots nutzen und vermeidest Seiteneffekte durch lokale Windows-Container- oder WSL-Konfigurationen.

4.2 Hyper-V-Netzwerk richtig wählen

Damit POS-Clients oder Testsysteme den virtuellen Drucker erreichen, muss die VM an einen passenden virtuellen Switch gebunden sein.

Switch-Typ	Einsatz
Extern	Die VM ist aus deinem LAN erreichbar. Für echte Netzwerktests meist die beste Wahl.
Intern	Kommunikation nur zwischen Host und VMs. Gut für Labors ohne Zugriff aus dem restlichen Netzwerk.
Privat	Nur VM-zu-VM. Für typische ESC/POS-Tests meist zu eingeschränkt.

4.3 Docker Desktop auf einem Windows-Hyper-V-Host

Falls du keinen separaten Linux-Gast betreiben möchtest, kannst du Docker Desktop auf dem Windows-System verwenden und Linux-Container ausführen. Docker Desktop unterstützt auf Windows WSL 2 und arbeitet je nach Modus mit virtualisierten Backends.

Danach kannst du denselben Containerbefehl auch in PowerShell ausführen:

docker run -d `
  --name escpos-netprinter `
  -p 515:515/tcp `
  -p 80:80/tcp `
  -p 9100:9100/tcp `
  --mount source=receiptVolume,target=/home/escpos-emu/web `
  gilbertfl/escpos-netprinter:3.2

Hinweis: Für saubere Erreichbarkeit aus anderen Systemen ist eine dedizierte Linux-VM unter Hyper-V oft berechenbarer als eine Desktop-Installation auf dem Host. Für kurze Tests funktioniert Docker Desktop dennoch meist problemlos.

7. Container aus dem Quellcode bauen

Wenn du das Image nicht aus Docker Hub verwenden möchtest, kannst du es laut Repository auch selbst bauen:

wget --show-progress https://github.com/gilbertfl/escpos-netprinter/archive/refs/tags/3.2.zip
unzip 3.2.zip
cd escpos-netprinter-3.2
docker build -t escpos-netprinter:3.2 .

Anschließend startest du den selbst gebauten Container:

docker run -d \
  --name escpos-netprinter \
  -p 515:515/tcp \
  -p 80:80/tcp \
  -p 9100:9100/tcp \
  --mount source=receiptVolume,target=/home/escpos-emu/web \
  escpos-netprinter:3.2

8. Wichtige Laufzeitpfade und Daten

Das Repository nennt mehrere Verzeichnisse innerhalb des Containers, die für Betrieb und Fehlersuche relevant sind.

Pfad im Container	Bedeutung
`/home/escpos-emu/web/`	Belege, Statusdaten und Logs
`/home/escpos-emu/web/receipts`	HTML-Belege
`/home/escpos-emu/web/tmp`	Temporäre Dateien, vor allem beim Debugging
`/home/escpos-emu/web/receipt_list.csv`	Liste der empfangenen Belege mit Dateipfaden

9. Debugging und Diagnose

7.1 Ausführliche Logs aktivieren

Das Projekt unterstützt die Umgebungsvariable ESCPOS_DEBUG=True. Damit werden laut README ausführlichere Logs für CUPS, JetDirect, ESC/POS-Konvertierung und die Weboberfläche erzeugt.

docker run -d \
  --name escpos-netprinter \
  -p 515:515/tcp \
  -p 80:80/tcp \
  -p 9100:9100/tcp \
  --mount source=receiptVolume,target=/home/escpos-emu/web \
  --env ESCPOS_DEBUG=True \
  gilbertfl/escpos-netprinter:3.2

7.2 Container-Logs anzeigen

docker logs escpos-netprinter

# fortlaufend ansehen

docker logs -f escpos-netprinter

7.3 CUPS-Oberfläche zusätzlich freischalten

Bei Problemen mit der CUPS-Schnittstelle kannst du zusätzlich Port 631 veröffentlichen:

docker run -d \
  --name escpos-netprinter \
  -p 515:515/tcp \
  -p 80:80/tcp \
  -p 9100:9100/tcp \
  -p 631:631/tcp \
  --mount source=receiptVolume,target=/home/escpos-emu/web \
  gilbertfl/escpos-netprinter:3.2

Achtung: Im README wird für die CUPS-Administration standardmäßig cupsadmin mit dem Passwort 123456 genannt. Ändere diese Zugangsdaten sofort oder nutze Port 631 nur kurzzeitig in einem isolierten Testnetz.

10. Testdruck durchführen

Für einen einfachen Funktionstest reicht es, rohe Daten an Port 9100 zu senden. Unter Linux kannst du beispielsweise mit nc testen:

printf 'Testbeleg\n\nHallo ESC/POS\n\n' | nc <IP-des-Containers-oder-der-VM> 9100

Wenn deine Anwendung bereits mit einem Netzwerk-Bondrucker arbeitet, trägst du einfach die IP-Adresse deiner VM oder deines Docker-Hosts und Port 9100 als Druckziel ein.

Erfolgskontrolle: Öffne danach die Weboberfläche und prüfe, ob ein neuer HTML-Beleg erzeugt wurde. So siehst du sofort, ob Netzwerk, Portfreigabe und ESC/POS-Verarbeitung funktionieren.

11. Sinnvolle Umgebungsvariablen

Variable	Standardwert	Zweck
`ESCPOS_DEBUG`	`false`	Ausführliche Debug-Ausgabe aktivieren
`PRINTER_PORT`	`9100`	JetDirect-Port
`FLASK_RUN_DEBUG`	`false`	Flask-Debug-Modus
`FLASK_RUN_PORT`	`80`	Port der Weboberfläche
`ESCPOS_TIMEZONE`	`America/Montreal`	Zeitzone für Datum und Uhrzeit

Beispiel mit angepasster Zeitzone:

docker run -d \
  --name escpos-netprinter \
  -p 515:515/tcp \
  -p 80:80/tcp \
  -p 9100:9100/tcp \
  --mount source=receiptVolume,target=/home/escpos-emu/web \
  --env ESCPOS_TIMEZONE=Europe/Vienna \
  gilbertfl/escpos-netprinter:3.2

12. Häufige Probleme auf Linux und Hyper-V

10.1 Weboberfläche ist erreichbar, aber kein Druck kommt an

Prüfe, ob der Client wirklich auf Port 9100 oder 515 sendet
Prüfe Firewall-Regeln auf Host und VM
Kontrolliere die Portveröffentlichung mit docker ps
Aktiviere ESCPOS_DEBUG=True und beobachte docker logs -f

10.2 Hyper-V-VM ist nicht aus dem Netzwerk erreichbar

Meist ist kein externer virtueller Switch konfiguriert
Prüfe die IP-Adresse der VM
Teste die Erreichbarkeit per ping oder Test-NetConnection
Stelle sicher, dass keine zusätzliche Windows-Firewall die Ports blockiert

10.3 Ausdrucke verschwinden nach Neustart

Dann fehlt meist der Mount auf /home/escpos-emu/web
Nutze ein Docker-Volume oder ein persistentes Host-Verzeichnis

10.4 Spezialsoftware spricht nicht mit dem Emulator

Im README wird ausdrücklich erwähnt, dass bestimmte Epson-Utilities nicht mit dem Emulator kommunizieren
Teste dann vorzugsweise mit einfachen Treibern, Rohdaten oder deiner eigentlichen Kassenanwendung

13. Empfehlung für die Praxis

Für produktionsnahe Tests empfiehlt sich meistens eine kleine Linux-VM unter Hyper-V mit externer Netzwerkanbindung. Diese Kombination ist übersichtlich, portabel und vermeidet unnötige Abhängigkeiten vom Windows-Desktop. Für schnelle lokale Tests genügt dagegen häufig Docker Desktop auf dem Host.

Praxis-Tipp: Wenn du mehrere POS-Systeme oder Treiber testen willst, lege Snapshots deiner Hyper-V-VM an. So kannst du verschiedene Konfigurationen fahren, ohne jedes Mal wieder bei null anzufangen.

14. Fazit

escpos-netprinter ist ein praktischer ESC/POS-Emulator für Labor, Entwicklung und Integrationstests. Besonders auf Linux oder in einer Hyper-V-Linux-VM lässt sich das Projekt sauber betreiben. Mit den Ports 9100, 515 und 80, einem persistenten Mount und optionalem Debugging hast du schnell eine virtuelle Bondrucker-Umgebung, die Papier spart und gleichzeitig gute Sicht auf die erzeugten Belege bietet.