asdfinit/rock-cloudprint repository overview

⁠Rock Cloud Print — Docker

A community-maintained Docker port of the Rock RMS⁠ Cloud Print proxy service.

The original application is Windows-only. This image runs as a headless Linux container with a browser-based admin UI, on any Linux server — including a Raspberry Pi or TrueNAS SCALE — on the same network as your label printers.

Rock RMS Server  ──WebSocket──▶  This container  ──TCP:9100──▶  Local Printer

Commonly used for Rock Check-in label printing where printers are on a local church network but the Rock server is cloud-hosted.

After any of the installs below: open http://<server-ip>:8080 → Settings → enter your Rock server URL and Proxy ID → Save & Reconnect. Then set a PIN under Settings → Security.

⁠Quick start (Linux server / Raspberry Pi)

# 1. Create a config folder (settings are written here by the web UI)
mkdir -p rock-cloudprint/config

# 2. Create docker-compose.yml
cat > rock-cloudprint/docker-compose.yml <<'EOF'
services:
  rock-cloudprint:
    image: asdfinit/rock-cloudprint:latest
    network_mode: host
    volumes:
      - ./config:/app/config
    restart: unless-stopped
EOF

# 3. Start the container
cd rock-cloudprint
docker compose up -d

# 4. Open the web UI
# Navigate to http://<server-ip>:8080

⁠Auto-start on reboot

sudo bash -c 'cat > /etc/systemd/system/rock-cloudprint.service <<EOF
[Unit]
Description=Rock Cloud Print Proxy
After=docker.service
Requires=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/rock-cloudprint
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=300

[Install]
WantedBy=multi-user.target
EOF'
sudo systemctl daemon-reload
sudo systemctl enable rock-cloudprint

⁠TrueNAS SCALE

TrueNAS SCALE 25.10 supports Docker Compose via Install via YAML in the Apps section.

1. In Datasets, create rock-cloudprint under your pool — e.g. tank/rock-cloudprint, path /mnt/tank/rock-cloudprint.
2. Apps → Discover → ⋮ (top right) → Install via YAML, name the app rock-cloudprint, and paste:

services:
  rock-cloudprint:
    image: asdfinit/rock-cloudprint:latest
    ports:
      - "8080:8080"
    volumes:
      - /mnt/tank/rock-cloudprint:/app/config
    restart: unless-stopped

Open http://<truenas-ip>:8080 and configure. Settings persist in the dataset and survive container updates.

⁠Portainer

Deploy as a Stack — Portainer's equivalent of a Compose file. Stacks → Add stack → Web editor, name it rock-cloudprint, paste, and Deploy the stack:

services:
  rock-cloudprint:
    image: asdfinit/rock-cloudprint:latest
    container_name: rock-cloudprint
    ports:
      - "8080:8080"
    volumes:
      - rock-cloudprint-config:/app/config
    restart: unless-stopped

volumes:
  rock-cloudprint-config:

⁠Configuration

Two ways. Environment variables take precedence over the web UI.

Web UI (recommended) — Settings tab:

Environment variables:

environment:
  - Url=https://origin.church.com
  - Id=da0BJR0Bpz
  - Name=Office Proxy
  - Password=mypin        # optional PIN to protect the web UI

⁠PIN / password protection

The web UI is open by default. Set a PIN. Anyone who can reach port 8080 can change every setting, and can upload a label and print it to any address they choose — which means the port offers a way to send arbitrary bytes to any host and port on your network. That is inherent to what a print proxy does, but it makes the PIN worth setting even on a network you trust.

Set it via Settings → Security → Set PIN, or with - Password=mypin in the docker-compose.yml environment block. Tokens are in-memory only, so users log in again after a restart.

⁠Networking

On a standard Linux server this image uses network_mode: host, so the container reaches printers at their local IP addresses (port 9100) and the web UI needs no port mapping.

On TrueNAS SCALE host networking is not available in the Apps system; use port mapping (ports: - "8080:8080") instead. The container still reaches LAN printers through the host.

⁠Printer addressing

Printers are configured in Rock, not in this app. In Rock's check-in printer settings, set the printer's local IP:

• 192.168.1.50 — default port 9100
• 192.168.1.50:9100 — explicit port

⁠CDN / origin URL

If your Rock site sits behind Cloudflare or another CDN, use the origin server URL rather than the primary domain. CDNs typically do not forward WebSocket upgrade requests, giving:

The server returned status code '400' when status code '101' was expected.

Your origin URL is often https://origin.yourdomain.com, or the direct IP/hostname of your web server.

⁠Updating

docker compose pull
docker compose up -d

Settings are stored in config/ outside the container and are unaffected by updates.

⁠Web UI reference

The running version is shown beside the title, next to a button that switches between the light and dark themes. The page follows your browser's own light/dark setting until you press it, then remembers what you chose.

⁠Blank labels

When check-in goes down, families fill in labels by hand — which only works if a supply of pre-printed blanks already exists. Each blank carries a security code, the same one on the child's tag and the parent's receipt, so pickup still matches when the names are handwritten.

The Blank Labels tab prints them. It needs nothing from the Rock server, and that is the point — the proxy already holds the templates and already talks to the printers, so it still works when Rock does not. Print them in advance, not during the outage.

Three demo templates are included, so there is something to print on a fresh install. They can be deleted, and downloaded again from the repository.

A label is a ZPL file with a placeholder where the code goes: WWW as the whole of a field (what Rock's own legacy labels use), or ??? anywhere inside one. Write it anywhere that produces ZPL and upload it. The label's size is fixed in the file by ^PW and ^LL, so load the stock that matches — the size is shown beside each label. Put anything in cutter mode (^MMC) last in the order, or the cut lands in the middle of a copy.

Codes are random from the digits and capital letters, or sequential. How many characters fit is decided by the label — the three demo templates are designed for three. Longer codes are clipped rather than shrunk, so preview first, or upload a template laid out for more. Sequential numbering is remembered between runs, so two batches printed months apart cannot carry the same codes, and codes are reserved before anything is sent, so a failed run leaves a gap rather than repeating itself later.

A few things worth knowing:

• Choose a printer that is not serving check-in. Nothing stops two things printing to the same printer at once.
• The run counts copies handed to the printer, not printed. A completed network write only means the bytes were accepted.
• There is no time limit on a run. A printer out of labels pauses and carries on when reloaded, so a slow run is usually waiting for paper. Cancel is the only thing that ends one early.
• The preview is drawn by Labelary⁠, so that one button needs internet access. Printing does not.

If the printer has a cutter, tick Has cutter beside the address and the proxy sends the cut commands itself — one cut after the last label of each copy. It uses the same commands Rock sends during check-in, so the cut no longer depends on which uploaded label happens to carry ^MMC.

Printers can be saved by name. The Printer box takes an address or the name of a saved printer, and the list under it narrows as you type. Press + to save what is in the box — the dialog asks for a name, the address, and whether that printer has a cutter, so the cutter setting comes back whenever the printer is chosen. The list is held on the proxy, so it is the same for everyone who opens the page, and whoever sets a printer up types its address once while everybody after them picks the name.

Capturing a label from Rock. Rock will not give you the ZPL for a label designed in its own designer, but the proxy is in the middle of every print. Capture from Rock catches one by being an ordinary printer: arm it, then point a printer address in Rock at this machine and print one label. It listens on 9100, only while armed, and stops after one label.

It is for a label designed as a blank — a normal check-in label has nothing to write on, so blanking one is useless. Expect the security code field to arrive empty: Rock substitutes its token before printing, and a test print has no attendance behind it. Fields are picked by position, and the list shows each field's font height, because the code is the one thing printed large.

Templates are stored in config/labels/, the record of used codes in config/blank-labels.json, and saved printers in config/printers.json — all inside the folder you already back up.

⁠Print failure notifications

The proxy can tell your Rock server when a printer fails, or when a print finishes too slowly to be any use, so somebody can be told. Off by default.

Once Rock is ready, configure it in Settings → Notifications: the webhook URL, the shared secret, and a quiet period. Then press Send test notification — it sends a real request and reports exactly what came back, so the URL, the secret, the webhook and the workflow are all proved at setup time rather than during an outage.

If Rock is configured correctly, pressing it may message people. That is how you know it worked.

A few things worth knowing:

• The webhook URL must be https — the shared secret travels in a request header. A plain http URL is refused rather than sent.
• Use the same host as your Rock server URL. Behind a CDN the webhook sees the CDN's address rather than your proxy's, and rejects it.
• Notifications are debounced per printer, per kind of problem, defaulting to a five minute quiet period. One printer failing ten times produces one notification; ten printers failing produce ten, because that is ten things to check.
• If a notification cannot be delivered, the dashboard shows a banner naming the actual fault — a rejected secret, a URL matching no webhook — rather than saying the request failed. It clears on the next success.

⁠Useful commands

docker compose pull          # pull latest image
docker compose up -d         # start / apply updates
docker compose logs -f       # live logs
docker compose restart       # restart container
docker compose down          # stop

⁠Source

github.com/The-Ark-Church/rock-cloud-print-docker⁠

Based on Rock RMS⁠ — licensed under the Rock Community License⁠.