Chapter 3. Server, Configuration & Security
Chapter 3. Server, Configuration & Security
3.1 Running the headless service
Run wxprint-server directly to start in console mode: it reads
~/.wxprint/config.json and listens. The log level comes from the
configuration; output goes to stderr.
Management arguments (process and exit):
| Argument | Action |
|---|---|
--install |
Register as a system service (alias --install-service) |
--uninstall |
Unregister the service (alias --uninstall-service) |
--service-status |
Query registration and running status |
3.2 Registering as a system service
wxprint-server --install detects the init system and registers:
| Platform | Detection & registration | Notes |
|---|---|---|
| Linux (systemd) | /run/systemd/system exists |
User-level unit (no root), automatic restart on failure |
| Linux (OpenRC) | /run/openrc active marker |
Alpine and friends; /etc/init.d needs root |
| Linux (sysvinit) | /etc/init.d + update-rc.d/chkconfig |
Devuan and friends; LSB script + start-stop-daemon |
| macOS | launchd | LaunchAgent |
| FreeBSD / NetBSD / OpenBSD | rc.d | Corresponding rc scripts |
| Windows | SCM service | Full service control protocol (Stop/Shutdown/Interrogate); runs as LocalSystem |
Notes:
- The Windows service runs as LocalSystem with its own configuration
directory, separate from the user-session
%USERPROFILE%\.wxprint\— on the same machine, choose either “service mode” or “tray mode”, not both, to avoid two diverging configurations. - The Linux user-level systemd unit follows the user login session;
for unattended servers enable lingering
(
loginctl enable-linger <user>).
3.3 Configuration file
~/.wxprint/config.json — shared by the tray settings dialog and
manual editing. Precedence: CLI flags > environment variables
(WXPRINT_*) > configuration file.
Main fields:
{
"bind": "127.0.0.1:8899",
"http_enabled": true,
"tls": {
"bind": "0.0.0.0:8898",
"cert": "/path/fullchain.pem",
"key": "/path/privkey.pem",
"self_signed": false,
"domain": null
},
"token": "",
"allow_private_url": true,
"allow_file_data": false,
"template_dir": "~/.wxprint/templates",
"data_dir": "~/.wxprint/data",
"spool_dir": "~/.wxprint/spool",
"default_printer": null,
"ui_theme": "dark",
"ui_lang": "",
"log_level": "error"
}
| Field | Default | Description |
|---|---|---|
bind |
127.0.0.1:8899 |
HTTP/WS listen address; 0.0.0.0 exposes it to the LAN |
http_enabled |
true |
Plain http/ws listener toggle |
tls |
null | Non-null enables HTTPS/WSS listening in parallel with plain, same routes; sub-fields bind (default 0.0.0.0:8898), cert/key (PEM), self_signed (true = generate a self-signed certificate for domain on save) |
token |
empty | Non-empty enables authentication |
allow_private_url |
true |
Allow fetching private/localhost URLs (data sources) |
allow_file_data |
false |
Whether loadJSON path may read arbitrary local files (default: restricted to data_dir) |
template_dir / data_dir / spool_dir |
same-named dirs under ~/.wxprint/ |
Template library / local data files / print spool directory |
default_printer |
empty | Default printer (empty = system default) |
ui_theme / ui_lang |
dark / empty |
Tray UI theme and language preference (ui_lang empty = follow the system) |
log_level |
error |
error/warn/info/debug |
3.4 Authentication (token)
When token is set, every API request must carry the credential in
any of three forms:
- Header
Authorization: Bearer <token> - Header
X-Wxprint-Token: <token> - Query parameter
?token=<token>(WS connections, preview component<img>tags, and other contexts that cannot set headers)
A missing or wrong token returns 401 E_AUTH. Recommended for LAN
deployments; local default is anonymous (reachable from 127.0.0.1
only). The tray settings dialog offers a “generate random” button.
3.5 TLS (HTTPS / WSS)
Use cases: the calling page itself is HTTPS (browser mixed-content restrictions force https/wss), or you want encrypted transport on the LAN.
- Custom certificate:
tls.cert+tls.key(PEM) — for environments with an internal CA. - Self-signed certificate: in the tray settings dialog choose “self-signed” and fill in the certificate domain; it is generated automatically on save. Clients must trust it once (browsers ask manually).
- Plain and TLS listeners run simultaneously (8899⁄8898 by default) with the same routes — existing http callers are unaffected; new https callers use the TLS port.
3.6 Other security items
| Item | Default | Description |
|---|---|---|
| URL fetch size / timeout | 10MB / 10s | Limits for template and data URL fetches |
| Local data files | restricted to ~/.wxprint/data/ |
Opened up by allow_file_data |
| CORS | * allowed |
Cross-origin calls from web pages are the norm for printing |
| Template execution surface | no I/O | Twig sandbox (no dangerous functions registered); HTML never executes JS |
| Job concurrency | serial rendering + serial output per printer | Queued, never rejected |
3.7 Service status page
Open http://127.0.0.1:8899/ in a browser: a read-only status page
shows the version, listen addresses (including TLS), printer list,
and recent jobs — the one-glance health check after deployment.