zplcore/designer repository overview

⁠zplCore Designer

A WYSIWYG label editor for your own application, plus a stateless render API: the editor runs in the browser (embed it with an iframe or the JS SDK), designs are JSON documents you store yourself, and the API turns them into ZPL, PNG, PDF or SVG. Built on the zplCore rendering engine. Website and documentation: https://zplcore.com/docs/designer/⁠

⁠Tags

No shell, no package manager, non-root user app (UID 1654), port 8080. The server keeps no state: any number of replicas, no sticky sessions.

⁠Quick start

docker run --rm -p 8080:8080 --read-only --tmpfs /tmp \
  -e ZPLCORE_DESIGNER__AUTH__MODE=apikey \
  -e ZPLCORE_DESIGNER__AUTH__APIKEYS__0=<your key, at least 16 characters> \
  zplcore/designer:1.0.0

Open http://localhost:8080/designer/⁠ – the editor UI. The API lives below /designer/api/ and needs the key in the header X-Api-Key:

# ZPL of a design document (one label per record)
curl -X POST localhost:8080/designer/api/zpl \
  -H 'X-Api-Key: <your key>' -H 'Content-Type: application/json' \
  -d '{"document":{"label":{"unit":"Mm","width":50.8,"height":25.4,"items":[{"type":"text","name":"title","x":3,"y":4,"width":44,"height":4,"fontSize":8,"dataField":"name"}]}},"records":[{"name":"Hello"}]}'

# the same label as PNG (also: api/render/pdf, api/render/svg)
curl -X POST localhost:8080/designer/api/render/png \
  -H 'X-Api-Key: <your key>' -H 'Content-Type: application/json' -d @request.json -o label.png

OpenAPI document: /designer/api/openapi/zplcore-designer.json. JS SDK for host pages: /designer/sdk/zplcore-designer.mjs (also .umd.js, .d.ts). Probes: /healthz (liveness), /readyz (renders a tiny label).

⁠Authentication

The mode is required: ZPLCORE_DESIGNER__AUTH__MODE. The static editor UI stays public, the API needs a key or a token.

Recommended for operation – read-only root file system with a writable /tmp, no capabilities, no privilege escalation:

docker run -p 8080:8080 --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges \
  -e ZPLCORE_DESIGNER__AUTH__MODE=apikey -e ZPLCORE_DESIGNER__AUTH__APIKEYS__0=<key> zplcore/designer:1.0.0

⁠Licence and evaluation mode

zplCore Designer is commercial software under the zplCore licence agreement: https://zplcore.com/legal/eula/⁠ (also in the image: /licenses/LICENSE.md; third-party notices: /licenses/THIRD-PARTY-NOTICES.md).

Without a licence key the Designer runs in evaluation mode: every feature works, but previews and outputs carry the zplCore.com TRIAL watermark. The offline licence key (product "Designer" plus an SDK licence of the same or a higher type) comes from the environment variable ZPLCORE_LICENSE (the key itself) or ZPLCORE_LICENSE_FILE (path of a mounted secret file). Licences: https://zplcore.com/pricing/⁠

⁠Configuration

Environment variables ZPLCORE_DESIGNER__… (ASP.NET Core configuration, section Designer):

Folders, mounted read-only and used when present: /fonts (printer fonts, e.g. E:NAME.TTF), /graphics (printer-memory graphics), /templates, /icons, /svg-fonts, /graphic-fonts (font families released for graphic text).

⁠Kubernetes

A Helm chart (non-root, read-only root file system, HPA, optional NetworkPolicy) is described in the documentation: https://zplcore.com/docs/designer/⁠ – API keys and the licence key come from existing Secrets only, never from values files.

⁠Verify the image

The images are signed with cosign; every platform image carries its SBOM (SPDX) as a signed attestation. Public key: https://zplcore.com/cosign.pub⁠

cosign verify --key cosign.pub zplcore/designer:1.0.0
# SBOM of one platform image (digests: docker buildx imagetools inspect zplcore/designer:1.0.0)
cosign verify-attestation --key cosign.pub --type spdxjson zplcore/designer@sha256:<digest of the platform image>

⁠Support

https://zplcore.com/contact/⁠ · [email protected]⁠