One Rust binary, printpapi — no runtime, no Python, no Node. HTTP handler + SQLite queue. The
dashboard is embedded in the binary.
client apps printpapi server agent (remote machine)
┌──────────────┐ POST /jobs ┌────────────────┐ long-poll ┌───────────────┐
│ n8n, scripts │ ────────────▶ │ HTTP handler │ ◀───────────── │ registers its │
│ your backend │ │ SQLite queue │ GET /agent/ │ printers, │ ──▶ printer
│ │ ◀──────────── │ (WAL + reaper)│ ─ job+bytes ─▶ │ polls, prints │ (USB / :9100
└──────────────┘ GET /jobs/id └────────────────┘ ◀── result ─── │ raw or pdf │ / CUPS)
│ └───────────────┘
GET / dashboard
- An agent registers its printers, then long-polls
GET /agent/jobs. - A client submits a job (
POST /jobs); the server decodes the payload and queues it. - The agent receives the job, downloads the bytes, prints, reports the result.
- The agent connects outbound only — no inbound ports on the printer's machine.
Environment variables:
| Var | Default | Meaning |
|---|---|---|
PRINTAPI_TOKEN |
(required) | Bootstrap/admin token — treat like a password |
PRINT_DB |
printpapi.db |
SQLite database path |
PRINT_PORT |
3460 |
Listen port |
LOG_REQUESTS |
(off) | Set to log every HTTP request |
PRINTAPI_SIGNUP |
closed |
open lets anyone create an org via POST /signup — for a hosted deployment, not a private box. PRINTAPI_SIGNUP, PRINTAPI_SIGNUP_QUOTA, PRINTAPI_JOB_RETENTION_DAYS and PRINTAPI_TERMS_VERSION (with its links) are start values: while PRINTAPI_OPERATOR_TOKEN is set, the operator console can override them at runtime (live settings). With the token set, any value other than open (closed, CLOSED, off, a typo) locks signup shut and no override can open it; blank means unset |
PUBLIC_URL |
(unset) | This server's own address, e.g. https://print.example. Only then does a password-reset mail carry a link (see api.md) |
SMTP_HOST |
(unset) | Mail server for password resets. Unset ⇒ the reset token is printed to stderr instead |
SMTP_PORT |
587 (465 with SMTP_SSL) |
|
SMTP_USER / SMTP_PASSWORD |
(unset) | Omit for an anonymous relay |
SMTP_FROM |
printpapi@localhost |
Envelope sender |
SMTP_SSL |
(off) | 1 for implicit TLS; otherwise STARTTLS is used |
SMTP_STARTTLS |
1 |
0 to disable STARTTLS (plaintext relay on a trusted network) |
PRINTAPI_PLANS |
(unset) | Billing catalogue: a JSON array of plans, or a path to a file holding one. Unset ⇒ no plans, no billing routes |
PRINTAPI_BILLING_SECRET |
(unset) | Shared secret for the POST /billing/webhook signature. Unset ⇒ the webhook answers 503 |
PRINTAPI_SIGNUP_QUOTA |
(unset: no quota) | Non-negative integer: the monthly job_quota of every org created through POST /signup, so a free signup cannot print without limit. 0 blocks printing. Orgs the root token creates (POST /orgs) are untouched, and a billing plan still overrides it per org. Not an integer stops the server at startup. With signup open and no quota, startup prints a warning |
PRINTAPI_JOB_RETENTION_DAYS |
(unset or 0: keep for ever) |
Positive integer N: see Retention. Not a positive integer stops the server at startup. With signup open and no retention, startup prints a warning |
PRINTAPI_TERMS_VERSION |
(unset: no consent asked) | A non-empty version string of at most 100 characters without control characters, e.g. 2026-11-13. Set: POST /signup must carry accept_terms equal to it, GET /health reports it with the links below, and the dashboard's sign-up form shows a checkbox for the terms and the data processing agreement. Each acceptance (org, user, version, time) is stored in the terms_acceptances table. See Self-signup. With signup open and no version, startup prints a warning |
PRINTAPI_TERMS_URL |
(required with the version) | http(s) link to the terms. Anything else, or a version without it, stops the server at startup |
PRINTAPI_DPA_URL, PRINTAPI_PRIVACY_URL |
(unset) | Optional http(s) links to the data processing agreement and the privacy policy, shown next to the checkbox. Anything else stops the server at startup |
PRINTAPI_FETCHES_PER_ORG |
4 with open signup or an operator token, else 0 (no cap) |
Payload downloads (*_uri, *_uri_post, label_uri) one org may have in flight at once; the next one answers 503. A non-negative integer, 0 = no cap; anything else stops the server at startup. Keeps one hosted tenant from using every download slot; a single-org box has no reason for it, since four hung upstream hosts would then block every other fetching job |
PRINTAPI_PRIVATE_URLS |
deny with open signup or an operator token, else allow |
deny: payload URLs (*_uri, *_uri_post), job callback_urls and org event_urls may only reach public addresses — no loopback, LAN, link-local/cloud-metadata or other private ranges, checked after DNS on every redirect hop. allow: anywhere (a self-hosted box fetching PDFs from an internal service). Set deny whenever people you do not trust get keys |
PRINTAPI_TRUSTED_PROXIES |
(unset: nobody) | Comma-separated IPs or CIDRs (IPv4 and IPv6, e.g. 127.0.0.1,::1 or the one pinned proxy address 172.30.0.2 of the Compose example; list nothing wider) of the reverse proxies in front of printpapi. Only a request whose socket peer is listed has its X-Forwarded-For read: the rightmost entry that is not itself listed is the client, which the signup throttle (IPv6 per /64) and the LOG_REQUESTS line then use. Unset, the socket peer is the client, so behind a proxy every signup shares one throttle slot. An invalid entry stops the server at startup. See Behind a reverse proxy |
PRINTAPI_OPEN_ENROLLMENT |
(off) | 1: any Bearer value enrolls a new agent into the default org (the v2 rule). Off: a new agent needs an issued key or the root token |
PRINTAPI_OPERATOR_TOKEN |
(unset: no operator API) | Set: the operator API under /operator/ is on (reads and writes: org changes, locks, deletes, invitations, reset mails, key revokes, each in the audit log; invitations and reset mails need SMTP_HOST and PUBLIC_URL), for the console of a hosted deployment, and so is hosted mode (private URLs denied, 4 downloads per org, unless you set them). At least 32 characters, not starting with sess_, different from PRINTAPI_TOKEN; anything else stops the server at startup. Unset, every /operator/ path answers 404 |
PRINTAPI_OPERATOR_FROM |
(required with the operator token) | Comma-separated IPs or CIDRs (the PRINTAPI_TRUSTED_PROXIES syntax) the operator token is accepted from, matched against the socket peer, never X-Forwarded-For. From any other address the token is an unknown credential. Missing or invalid with the token set stops the server at startup |
PRINTAPI_TOKEN=change-me PRINT_DB=data/printpapi.db ./printpapiprintpapi --version prints the version. An existing printpapi.db from the Python server
(v2.5.1 or older) opens unchanged — the schema is the same, apart from a few additive indexes.
Same environment, same database, same API. The migration guide walks through the server and agent upgrade, the defaults that are stricter in v3 and how to roll back.
Download the printpapi-server-<platform> archive from the
latest release and unpack it, or build it
(needs Rust; on Windows the GNU or MSVC toolchain):
cargo build --release -p printpapi-server # -> target/release/printpapiThe build embeds the dashboard from crates/server/web (committed), so no Node is needed to build
the server. See Dashboard for changing the UI.
Pull the prebuilt image (published to GHCR on every release, amd64 + arm64):
docker run -e PRINTAPI_TOKEN=change-me -p 3460:3460 \
-v $PWD/data:/app/data -e PRINT_DB=/app/data/printpapi.db \
ghcr.io/lukiprince/printpapiThe -v + PRINT_DB keep the SQLite DB (jobs and issued API keys) on the host, so
recreating the container doesn't wipe them. docker compose up -d does the same with a named
volume — see docker-compose.yml.
Build it yourself instead: docker build -t printpapi . then run the same command with
printpapi in place of the ghcr.io/... image.
The image is distroless (gcr.io/distroless/cc-debian13) and holds just the printpapi binary —
no Python, no cups-client, no shell (so docker exec ... sh does not work). The build has three
stages: node:22-slim compiles the dashboard, a Rust stage builds the server with it embedded
(cross-compiled for arm64), and only the binary is copied into the runtime image. The container
runs as root, as the Python image did, so an existing data volume stays writable.
GET / serves a static, secret-free React dashboard: a live overview (queue counters,
job-outcome breakdown, activity feed), printers online/offline, searchable job history with
cancel, one-click test print, API-key management, a Team page (add or remove the people who
may sign in, change your own password), a Settings page (this month's jobs against the org's
quota, the agent-event URL, the Shopify webhook secret), agent install instructions, light/dark
theme and a ⌘K command palette. You sign in with an account — creating one yourself where the
operator allows it, and resetting a forgotten password by e-mail — or paste a token; either way
the credential is kept in
localStorage and sent as a bearer header — nothing sensitive lives in the served files. The test print sends a
PDF only to PDF-capable printers and a ZPL label to everything else.
Where it comes from. The source is a Next.js app in web/ (App Router,
TypeScript, Tailwind v4, shadcn/ui on Radix, Motion for animation).
It is built as a static export — plain HTML/JS/CSS — committed to crates/server/web and
embedded into the binary at compile time. A plain cargo build checkout therefore has a
working dashboard with no Node installed, and the running server needs no files next to it.
Changing the UI:
PRINTAPI_TOKEN=change-me cargo run -p printpapi-server # the API, on :3460
cd web
npm install
npm run dev # localhost:3000 with hot reload; API calls are proxied to :3460 in dev
npm run build:app # static export -> web/out, then synced into crates/server/web (commit that)npm run dev only works against a running server — it has no API of its own. The dev-only proxy
lives in web/next.config.ts; point it elsewhere with PRINTPAPI_ORIGIN=http://host:port. It is
stripped from the production build, where the server serves the bundle and the API together.
crates/server/web is build output — change web/, run npm run build:app, commit both, then
rebuild the binary (the bundle is embedded at compile time, so a running server keeps the old UI
until then).
npm run build:demo builds the hosted demo (start page plus the dashboard against an in-browser
fake API) into web/out-demo; it is never synced into the binary.
Asset paths under /_next/static/ are content-hashed and served immutable; the HTML is
served no-cache. Requests are confined to the embedded bundle — a path that escapes it 404s.
The bootstrap PRINTAPI_TOKEN is root: it can do everything, including issuing scoped
per-client keys (one per integration). Issued keys can submit and read jobs, but can't manage
keys. Keys are stored SHA-256-hashed; revoking one cuts access immediately.
curl -s -X POST localhost:3460/apikeys \
-H 'Authorization: Bearer <PRINTAPI_TOKEN>' -H 'Content-Type: application/json' \
-d '{"label":"n8n"}'
# -> {"id":1,"label":"n8n","org_id":1,"key":"<shown once — store it>"}Add "org_id" to put the key (and any agent registering with it) in another org — see
Multi-tenancy. Without it, everything stays in the single default org,
which is what a plain self-hosted install wants.
So nobody has to paste the root token into a browser, an org's people can sign in with an e-mail and password. Root seeds the first user, that user invites the rest and manages the org's keys:
curl -s -X POST localhost:3460/orgs/1/users \
-H 'Authorization: Bearer <PRINTAPI_TOKEN>' -H 'Content-Type: application/json' \
-d '{"email":"ops@yourshop.example","password":"a long passphrase"}'The dashboard's sign-in screen then takes those credentials (the token field is still there for
root and for machine keys). Passwords are salted scrypt hashes, sessions expire after 30 days,
and a machine key can never manage keys or users — see
Accounts and login.
SQLite in WAL mode with an atomic claim. A visibility-timeout reaper requeues jobs whose agent went silent and fails them after a bounded number of retries. Reaper errors are logged to stderr.
A job holds its payload (labels, packing slips, addresses) until you say otherwise. With
PRINTAPI_JOB_RETENTION_DAYS=N the reaper runs, at most once an hour:
- a job still
queuedafter N days (its agent never came back) and without anexpire_afterdeadline is failed witherror: "retention"and loses payload and title. Its callback URL stays, so the client's outcome webhook still fires (the next step drops it N days later). A job with a deadline waits for it and is failed asexpired; - a
done,failedorcancelledjob finished more than N days ago loses its payload, title and callback URL. Its row (state, printer, times) stays; - of those, the rows created before the current UTC month and finished more than
max(N, 7)days ago are deleted. The current month's rows stay, because the monthly quota counts them: deleting them would hand quota back. The 7 day floor keeps the row, and with it the idempotency key, long enough for a webhook redelivery (Shopify retries for 48 h).
claimed jobs are never touched. The server always opens SQLite with secure_delete=ON, so freed
pages are zeroed instead of keeping the old bytes (this also covers deleting an org), and after a
pass that changed rows, and after deleting an org, it truncates the WAL (PRAGMA wal_checkpoint(TRUNCATE)),
so cleared payloads do not stay in printpapi.db-wal. A long-running read can block that truncate;
the server then logs one line and does not wait. The retention pass tries again on its next run; a
deleted org's frames stay in the WAL until the next truncate or checkpoint. Data freed by an earlier version is not overwritten: to erase it,
stop the server and run VACUUM once (for example sqlite3 printpapi.db VACUUM). The server never
does that by itself. Backups keep what they copied until you rotate them out: set your backup
retention to match.
Enforced at every trust boundary: bearer auth on every endpoint, constant-time token compare,
SHA-256-hashed agent, client and session credentials, salted scrypt password hashes with a
throttled and non-enumerating login, http(s)-only URL fetches, 32 MB request-body cap,
no shell=True, agent temp-file cleanup, and job payloads scoped so an agent can only touch
its own jobs.
The PrintNode-compatible layer accepts HTTP Basic auth as well — the key rides in the username, so it is the same secret with the same org scope, but base64 in a header is not encryption: put TLS in front of it, as you should for the bearer token anyway.
Star CloudPRNT printers carry the client key in their polling URL
(/cloudprnt/<key>), because the printer appends its own query string to whatever URL it is given.
A key in a URL ends up in access logs and proxy history — prefer the printer's Basic-auth
User Name field where the model offers one, and revoke the key
(DELETE /apikeys/{id}) if a device is lost.
The server speaks plain HTTP — put your own reverse proxy / TLS in front for anything beyond the LAN. Vulnerability reports: see SECURITY.md.
Behind a proxy every request comes from the proxy's address, so the signup throttle would see one
client. Set PRINTAPI_TRUSTED_PROXIES to the proxy's address and printpapi reads the real client
from X-Forwarded-For. List only the proxy: a request from any other peer keeps its socket
address, whatever header it sends. Caddy's reverse_proxy replaces an incoming
X-Forwarded-For from an untrusted client with its own, so it needs no extra configuration
(Caddy docs).
With Docker Compose the peer printpapi sees is Caddy's container address, which moves unless it
is pinned. Put both on one user-defined network with a fixed subnet, give Caddy a fixed
ipv4_address and trust exactly that address, not the whole bridge range. The ip_range keeps
Docker's dynamic addresses (printpapi's own) out of the lower half of the subnet, so printpapi can
never be handed Caddy's fixed address. Publish no port for
printpapi, only Caddy's 80 and 443: a published printpapi port plus a trusted bridge range would
let a direct caller's header be believed.
services:
printpapi:
image: ghcr.io/lukiprince/printpapi:latest
environment:
PRINTAPI_TOKEN: change-me
PRINTAPI_SIGNUP: open
PRINT_DB: /app/data/printpapi.db
PRINTAPI_TRUSTED_PROXIES: 172.30.0.2 # Caddy's address below, nothing wider
volumes: [printpapi-data:/app/data]
networks: [edge] # no `ports:` for printpapi
caddy:
image: caddy:2
ports: ["80:80", "443:443"]
volumes: [./Caddyfile:/etc/caddy/Caddyfile:ro, caddy-data:/data]
networks:
edge:
ipv4_address: 172.30.0.2
networks:
edge:
ipam:
config:
- subnet: 172.30.0.0/24
ip_range: 172.30.0.128/25 # dynamic pool: never hands out 172.30.0.2
volumes:
printpapi-data:
caddy-data:print.example.com {
reverse_proxy printpapi:3460
}