Instance ops

Run a dedicated customer instance with clear access boundaries.

This page combines the new-server checklist, the access model, and copy-paste request examples for operator tooling.

Open pricing Open subscription Open Swagger

New server runbook

Provision the host once, then hand it to the customer.

Deploy the ManagedWeb host on the new server or on a dedicated pair behind a load balancer.
Set `ZPL_RENDER_OPERATOR_TOKEN` to a long random value before first start.
Set `ZPL_RENDER_API_KEY_ISSUER_TOKEN` if your operator tooling should mint premium API keys.
Set `PAYPAL_IPN_SANDBOX=1` while testing the listener against the sandbox, or override `PAYPAL_IPN_ENDPOINT` explicitly if needed.
Keep `app-data/` on persistent storage so the SQLite state survives restarts.
Call `POST /api/instance/provision` with the customer metadata and dedicated mode.
Fetch `GET /api/instance/provisioning` and follow the checklist in the manifest.
Verify DNS, TLS, `/health`, and the support mailbox before handing over the URL.

Access model

Use the right secret for the right job.

ZPL_RENDER_OPERATOR_TOKEN unlocks provisioning, cancellation, and reactivation.
ZPL_RENDER_API_KEY_ISSUER_TOKEN allows the protected POST /api/keys route to issue Plus or Business keys.
API keys are generated as zr_..., stored hashed in api-keys.json, and only shown once at creation time.
Customers send their key as X-Api-Key or Authorization: Bearer ....
For true exclusivity, add VPN, IP allowlisting, or reverse-proxy auth in front of the host. API keys alone do not turn the instance into a private network boundary.

Why dedicated

High throughput comes from isolation plus the renderer pool.

Shared mode already uses the native renderer pool, compression, and batch rendering. A dedicated deployment adds customer isolation, predictable capacity, and a clean offboarding path.

The code path for a dedicated customer instance is the same ManagedWeb host, but the instance profile, support email, and HA metadata are stored separately in app-data/zpl-instance.db.

Provisioning request

Provision a dedicated customer instance.

Send this request from an operator machine that can present X-ZPL-Operator-Token.

curl.exe -X POST "https://renderlabels.example.com/api/instance/provision" ^
  -H "X-ZPL-Operator-Token: <operator-token>" ^
  -H "Content-Type: application/json" ^
  -d "{\"customerName\":\"Acme GmbH\",\"customerEmail\":\"ops@acme.example\",\"planCode\":\"dedicated\",\"instanceMode\":\"dedicated\",\"status\":\"active\",\"primaryUrl\":\"https://labels.acme.example\",\"healthUrl\":\"/health\",\"supportEmail\":\"support@acme.example\",\"highAvailabilityEnabled\":true,\"replicaCount\":2,\"region\":\"eu-central-1\",\"notes\":\"Dedicated customer deployment\"}"

After provisioning, open GET /api/instance/provisioning to download the checklist and the environment block for the target server.

curl.exe -X GET "https://renderlabels.example.com/api/instance/provisioning" ^
  -H "X-ZPL-Operator-Token: <operator-token>"

API key issuance

Generate a customer API key once, then deliver it securely.

Only Plus and Business keys can be issued through the protected route. The raw value is returned once and must be shown or stored by your operator tooling immediately.

curl.exe -X POST "https://renderlabels.example.com/api/keys" ^
  -H "X-Api-Issuer-Token: <issuer-token>" ^
  -H "Content-Type: application/json" ^
  -d "{\"plan\":\"plus\",\"label\":\"Acme production key\"}"

The response contains keyId, apiKey, the plan metadata, and the preferred server name. Keep the raw key out of logs and pass it to the customer through your secure delivery path.

Customer usage

Use the key on the render API.

The customer can use the key in either header form below.

curl.exe -X POST "https://renderlabels.example.com/api/render" ^
  -H "X-Api-Key: <customer-key>" ^
  -H "Content-Type: application/json" ^
  -d "{\"zpl\":\"^XA^FO50,50^FDHello World^FS^XZ\",\"includeImage\":true}"

curl.exe -X POST "https://renderlabels.example.com/api/render" ^
  -H "Authorization: Bearer <customer-key>" ^
  -H "Content-Type: application/json" ^
  -d "{\"zpl\":\"^XA^FO50,50^FDHello World^FS^XZ\",\"includeImage\":true}"

Operational checklist

Use the manifest as the handoff document.

The manifest gives you the exact environment variables and offboarding steps that belong to the current instance profile.

Fetch manifest

Before handoff

Verify DNS, TLS, health, support email, and the customer-facing URL.

Offboarding

Cancel the instance, block traffic, archive app-data/, and reactivate only with the operator token if needed.