zplcore/server repository overview

⁠zplCore Server

Templates live on the server, your application sends the data and gets labels back: ZPL, PNG, SVG, PDF, ZIP or JSON. Built on the zplCore rendering engine. Website and documentation: https://zplcore.com/server/⁠

⁠Tags

Both images: no shell, no package manager, non-root user app (UID 1654), port 8080.

⁠Quick start

Put your label templates into a folder – zplCore label JSON or zplCore Designer documents (*.json). The path below the folder without .json is the template name (./templates/shipping/parcel.json → shipping/parcel).

docker run --rm -p 8080:8080 \
  -v ./templates:/templates:ro \
  -e ZPLCORE__AUTH__MODE=apikey \
  -e ZPLCORE__AUTH__APIKEYS__0=<your key, at least 16 characters> \
  zplcore/server:1.0.0

# ZPL (default)
curl -X POST localhost:8080/v1/labels/shipping/parcel \
  -H 'X-Api-Key: <your key>' -H 'Content-Type: application/json' \
  -d '[{"Name":"Anna Huber","City":"Vienna"}]'

# the same label as PNG (PDF: application/pdf, several labels as ZIP: application/zip)
curl -X POST localhost:8080/v1/labels/shipping/parcel \
  -H 'X-Api-Key: <your key>' -H 'Content-Type: application/json' -H 'Accept: image/png' \
  -d '[{"Name":"Anna Huber","City":"Vienna"}]' -o label.png

The authentication mode is required and has no default: apikey, jwt (OIDC: ZPLCORE__AUTH__AUTHORITY, ZPLCORE__AUTH__AUDIENCE) or none (local tests, or behind your own proxy). Without it the container stops with exit code 2 and names the setting.

Recommended for operation – read-only root file system, no capabilities, no privilege escalation:

docker run -p 8080:8080 --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges \
  -v ./templates:/templates:ro -e ZPLCORE__AUTH__MODE=apikey -e ZPLCORE__AUTH__APIKEYS__0=<key> zplcore/server:1.0.0

⁠Licence and evaluation mode

zplCore Server 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 server runs in evaluation mode: every feature works, without a time limit, but every output carries the zplCore.com TRIAL watermark (SVG comes as an embedded image). Responses name the mode in the header X-ZplCore-License (evaluation or licensed), /ready (with authentication) shows it as well. Licences: https://zplcore.com/pricing/⁠

The offline licence key is read from the secret file /run/secrets/zplcore-license (Docker/Kubernetes secret, reloaded when it changes) or from ZPLCORE__LICENSE__KEY.

⁠Configuration

• Mount /config/zplcore.yaml, or set any key as an environment variable ZPLCORE__SECTION__KEY (e.g. ZPLCORE__AUTH__MODE). Secrets (API keys, licence key, connection strings) never belong into the YAML file – the server refuses to start with them there; use secret files or environment variables.
• Data in: JSON (object, array, or {"records": [...], "variables": {...}}), NDJSON and CSV (streamed).
• Labels out (Accept): application/vnd.zpl (default), image/png, image/svg+xml (one label), application/pdf, application/zip, application/json (report).
• Template sources besides the volume: S3 (and S3-compatible stores), Azure Blob Storage, Google Cloud Storage, HTTP; git through a git-sync sidecar. Named database queries: SQLite, PostgreSQL, MySQL, SQL Server, REST (Oracle in -full).
• Printing to network printers, storage, webhooks, asynchronous jobs and batches.
• Probes: /health, /ready. API reference: /docs, OpenAPI document: /openapi/v1.json. Prometheus metrics are off by default: ZPLCORE__METRICS__ENABLED=true (own port: ZPLCORE__METRICS__PORT=9464).

⁠Oracle (-full only)

zplCore Server does not ship the Oracle driver. Add it in your own image; the Oracle licence applies between you and Oracle:

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS oracle
ARG TARGETARCH
WORKDIR /driver
RUN dotnet new classlib -n OracleDriver -o . -f net10.0 && dotnet add package Oracle.ManagedDataAccess.Core \
 && dotnet publish -c Release -r linux-$([ "$TARGETARCH" = "arm64" ] && echo arm64 || echo x64) --self-contained false -o /out

FROM zplcore/server:1.0.0-full
COPY --from=oracle /out/ /app/drivers/oracle/

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

⁠Support

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