---
title: 'CUPS-Server für Netzwerkdrucker (Videntis)'
description: 'Einen CUPS-Server als Docker-Service bereitstellen und mit den Etikettendruckern der Videntis-Erweiterung verbinden.'
navLabel: 'CUPS-Drucker'
navIcon: '🖨️'
---

import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"
import { Badge } from "@/components/ui/badge"
import { Icon } from "@/components/ui/icon"

Die Videntis-Erweiterung kann Etiketten statt als PDF-Download direkt an einen im Netzwerk erreichbaren Drucker senden (Format-Ausgabeart „Netzwerkdrucker" — siehe [Etiketten & Drucker](/docs/benutzerhandbuch/verwaltung/etiketten-drucker)). Dieses Kapitel beschreibt die Infrastruktur-Seite davon: einen CUPS-Server bereitstellen, an den CrispyCMS Druckaufträge schicken kann.

<Alert class="mt-4">
  <Icon name="info" />
  <AlertTitle>CrispyCMS betreibt keinen eigenen CUPS-Dienst</AlertTitle>
  <AlertDescription>
    <p>Der CrispyCMS-Container enthält lediglich das CUPS-Client-Werkzeug (<code>lp</code> / <code>lpstat</code> aus dem Debian-Paket <code>cups-client</code>), mit dem Druckaufträge über das IPP-Protokoll an einen <em>entfernten</em> CUPS-Server geschickt werden (<code>lp -h host:port -d warteschlange ...</code>). Der eigentliche CUPS-Server mit dem Druckertreiber läuft als separater Dienst — typischerweise ein weiterer Container im selben Docker-Netzwerk.</p>
  </AlertDescription>
</Alert>

---

## CUPS-Server-Image

Für einen einsatzbereiten CUPS-Server steht ein von BL Netzwerke gepflegtes Image bereit:

```bash
docker pull images.crispycms.de/distribution/cupsd
```

Binden Sie es als eigenen Service in Ihre `docker-compose.yml` ein, im selben Docker-Netzwerk wie den CrispyCMS-Container, damit dieser den CUPS-Server über den internen Servicenamen erreichen kann:

```yaml
services:
  crispycms:
    # ... bestehende CrispyCMS-Konfiguration ...
    networks:
      - crispy-net

  cups:
    image: images.crispycms.de/distribution/cupsd
    restart: unless-stopped
    ports:
      # 631 nur nach außen freigeben, wenn Sie direkt (z. B. für die
      # CUPS-Weboberfläche) von außerhalb des Docker-Netzwerks zugreifen
      # möchten. Für den reinen Betrieb mit CrispyCMS genügt die
      # interne Erreichbarkeit über das gemeinsame Netzwerk.
      - "631:631"
    volumes:
      - cups_data:/etc/cups
    networks:
      - crispy-net

volumes:
  cups_data:

networks:
  crispy-net:
    driver: bridge
```

<Alert variant="destructive" class="mt-4">
  <Icon name="alert-circle" />
  <AlertTitle>Image-spezifische Konfiguration prüfen</AlertTitle>
  <AlertDescription>
    <p>Prüfen Sie vor dem produktiven Einsatz die aktuell verfügbaren Tags sowie eventuelle Umgebungsvariablen des <code>distribution/cupsd</code>-Images (z. B. für einen Admin-Zugang zur CUPS-Weboberfläche) — diese können sich zwischen Versionen ändern. Das obige Beispiel zeigt die minimale Netzwerk-/Volume-Einbindung, die für die Anbindung an Videntis notwendig ist.</p>
  </AlertDescription>
</Alert>

---

## Drucker/Warteschlange im CUPS-Server anlegen

Nach dem Start des Containers erreichen Sie die CUPS-Weboberfläche unter `http://<host>:631` (bzw. `https://` je nach Image-Konfiguration). Dort — oder per `lpadmin` innerhalb des Containers — legen Sie für jeden physischen Drucker eine **Warteschlange (Queue)** mit dem passenden Treiber an (z. B. Brothers offizieller Linux-Treiber für einen QL-820NWBc). Der dabei vergebene **Warteschlangenname** ist der Wert, den Sie später in Videntis unter „Warteschlangenname" eintragen.

```bash
# Beispiel: Innerhalb des CUPS-Containers eine Warteschlange manuell anlegen
docker compose exec cups lpadmin -p ql820 -E -v ipp://192.168.1.50/ipp/print -m everywhere
docker compose exec cups cupsenable ql820
docker compose exec cups cupsaccept ql820
```

Der genaue Weg (IPP-Everywhere, herstellereigener Treiber, USB-über-Netzwerk-Bridge o. Ä.) hängt vom jeweiligen Druckermodell ab und ist unabhängig von CrispyCMS/Videntis — sobald die Warteschlange im CUPS-Server funktioniert (testen Sie mit `lp -d ql820 testdatei.pdf` direkt auf dem CUPS-Server), ist der CrispyCMS-seitige Teil nur noch Konfiguration.

---

## Drucker in Videntis anlegen

Tragen Sie unter **Verwalten → Drucker → Drucker hinzufügen** die Verbindungsdaten zum eben eingerichteten CUPS-Server ein:

| Feld | Wert im Beispiel oben |
| :--- | :--- |
| **CUPS-Server (Host/IP)** | `cups` (der Docker-Servicename aus der `docker-compose.yml`, sofern CrispyCMS und der CUPS-Server im selben Docker-Netzwerk laufen) |
| **Port** | `631` |
| **Warteschlangenname** | `ql820` (oder der von Ihnen vergebene Name) |

Klicken Sie anschließend auf **Verbindung testen** — Videntis führt dazu intern `lpstat -h cups:631 -p ql820` aus und meldet, ob der Server erreichbar ist und die Warteschlange dort existiert. Erst danach sollten Sie den Drucker einem Etikettenformat mit Ausgabeart „Netzwerkdrucker" zuweisen (siehe [Etiketten & Drucker](/docs/benutzerhandbuch/verwaltung/etiketten-drucker)).

---

## Fehlerbehebung

**„lpstat: No such file or directory" / „lp: command not found"**
Das `cups-client`-Paket fehlt im CrispyCMS-Image. Es ist seit Version 26.08 standardmäßig im offiziellen `Dockerfile` enthalten; bei einem selbst angepassten Image stellen Sie sicher, dass `cups-client` installiert ist, und bauen den Container neu (`docker compose build`, ein reiner Neustart genügt nicht).

**„Verbindung fehlgeschlagen: timeout"**
Prüfen Sie, ob CrispyCMS und der CUPS-Server im selben Docker-Netzwerk hängen und der Servicename als Host korrekt eingetragen ist. Ein direkter Verbindungstest aus dem CrispyCMS-Container heraus hilft bei der Eingrenzung:

```bash
docker compose exec crispycms lpstat -h cups:631 -p ql820
```

**Druckauftrag schlägt fehl, obwohl „Verbindung testen" erfolgreich war**
Die Warteschlange existiert und ist erreichbar, aber möglicherweise offline, im Fehlerzustand oder das PDF konnte vom Treiber nicht verarbeitet werden. Prüfen Sie den Warteschlangenstatus direkt auf dem CUPS-Server (`lpstat -p ql820 -l` bzw. über die CUPS-Weboberfläche) sowie die konkrete Fehlermeldung in Videntis unter **Verwalten → Druckwarteschlange**.