Saltar al contenido principal

Print Bridge — Deployment Guide

This guide is for implementation technicians and restaurant IT staff deploying Print Bridge at a client location.

What is Print Bridge?​

Print Bridge is a small app that runs on a Windows, macOS, or Linux PC inside the restaurant. It connects to FlowPOS in the cloud and sends kitchen orders and receipts to thermal printers on the local network (or via USB).

[FlowPOS Cloud] ──── Internet ────▶ [Print Bridge PC] ──── LAN ────▶ [Thermal Printer]

Print Bridge runs as a Docker container and includes a web UI accessible from any browser on the same network.

Requirements​

Hardware​

  • A PC, Mini PC, or server that stays on during restaurant hours
  • Same LAN as the thermal printers
  • Internet access (to reach FlowPOS)

Software​

Network​

  • Port 3456 must be open on the Print Bridge PC's firewall (for the web UI and API)
  • The PC must be able to reach the FlowPOS API URL (usually https://api.flowpos.app for production)
  • Printers must be reachable via TCP/IP (port 9100) or USB from the same PC

Step 1 — Prepare environment values​

You need two values before starting:

VariableDescriptionExample
BRIDGE_SECRET32-byte hex master secret — keeps the device token encrypted at resta3f8...c2d1 (64 chars)
FLOWPOS_API_URLRoot URL of the FlowPOS backendhttps://api.flowpos.app

No Firebase Admin credentials are required. Firebase token validation is proxied through the FlowPOS backend — only the bridge secret is needed on the client machine.

Generating BRIDGE_SECRET (if this is a new installation):

# Run this once and save the output — it never changes for this installation
openssl rand -hex 32

Keep BRIDGE_SECRET safe. If it is lost and the container is recreated, the device token becomes unreadable and the bridge must be re-paired.

Step 2 — Create the environment file​

On the Print Bridge PC, create a file called .env in a directory of your choice (e.g. C:\flowpos\print-bridge\.env or /opt/print-bridge/.env):

BRIDGE_SECRET=<64-char hex from Step 1>
FLOWPOS_API_URL=https://api.flowpos.app
PORT=3456

For staging environments use FLOWPOS_API_URL=https://api-staging.flowpos.app.

Step 3 — Create the docker-compose file​

In the same directory as .env, create docker-compose.yml:

services:
  print-bridge:
    image: ghcr.io/fixxrepo/flowpos-workspace/print-bridge:latest
    ports:
      - "${PORT:-3456}:3456"
    volumes:
      - print-bridge-data:/app/data
    env_file:
      - .env
    stop_grace_period: 30s
    restart: unless-stopped
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      WATCHTOWER_LABEL_ENABLE: "true"
      WATCHTOWER_CLEANUP: "true"
      WATCHTOWER_SCHEDULE: "0 0 3 * * *"
    restart: unless-stopped

volumes:
  print-bridge-data:
    driver: local

Watchtower checks for a new image every night at 3 AM and updates automatically. Remove the watchtower service if you prefer manual updates.

Step 4 — Start the container​

Open a terminal in the directory containing docker-compose.yml:

docker compose up -d

Verify it is running:

docker compose ps
# Should show print-bridge as "running"

docker compose logs --tail 20
# Should show: [startup] Print Bridge listening on 0.0.0.0:3456
# Should show: [startup] apiUrl seeded from FLOWPOS_API_URL: https://api.flowpos.app

Step 5 — First-time setup in the web UI​

Open a browser on the Print Bridge PC (or any device on the same LAN) and go to:

http://<print-bridge-pc-ip>:3456

If you are on the same PC: http://localhost:3456

5.1 — Pair with FlowPOS (do this before signing in)​

The bridge must be paired before you can log in with a FlowPOS account. The Config page is accessible without signing in.

In FlowPOS (web app or PWA):

  1. Go to Restaurant → Kitchen Stations
  2. Click Pair Print Bridge
  3. A pairing code will appear (format: XXXX-XXXX), valid for 10 minutes

In the Print Bridge UI:

  1. Click Config in the top navigation (or go directly to http://<ip>:3456/config)
  2. The FlowPOS API URL field should already be populated from FLOWPOS_API_URL — verify it is correct
  3. Enter the pairing code in the Pairing Code field
  4. Click Pair
  5. The status should change to Paired and show the business name and location

5.2 — Sign in​

Now that the bridge is paired, go to http://<ip>:3456/login and sign in with your FlowPOS account (email + password). This is the same account you use to log in to FlowPOS. The bridge will authenticate by forwarding your credentials to the FlowPOS backend — no Firebase credentials are needed on this machine.

If you prefer a local password instead of a FlowPOS account:

  1. Set a local password on the Config page (scroll to Local fallback password)
  2. On the login page, click Local password and enter the password you set

5.3 — Add printers​

  1. Click Printers in the top navigation
  2. Click Add Printer
  3. Fill in the details:
FieldDescription
LabelA name for this printer (e.g. "Kitchen", "Bar")
ConnectionTCP for network printers, USB for directly connected printers
Printer address(TCP) e.g. tcp://192.168.1.100:9100
USB Device(USB) Device path, e.g. /dev/ttyUSB0. Click Scan USB to detect
Paper width80mm (most common) or 58mm
StationsSelect the kitchen stations this printer should serve
CopiesHow many copies to print per ticket (1–5)
  1. Click Save

5.4 — Start the agent​

  1. On the Status page, click Start Agent
  2. The agent status should change to Running
  3. Each printer row will show its connection status (Connected / Disconnected)

5.5 — Test print​

  1. Go to Printers
  2. Click Test Print on the printer you want to verify
  3. The printer should feed and cut a test slip

Step 6 — Verify end-to-end​

  1. In the FlowPOS PWA (or POS terminal), create a test order and send it to the kitchen
  2. The ticket should print on the assigned printer within a few seconds
  3. On the Print Bridge Status page, the Recent Jobs section should show the job with status printed

Updating Print Bridge​

If you set up Watchtower, updates happen automatically at 3 AM. To update manually:

docker compose pull
docker compose up -d

Pairing, printer config, and all settings are stored in the Docker volume and survive updates.

Restarting and rebooting​

The container is set to restart: unless-stopped — it starts automatically when Docker starts. No manual action is needed after a reboot.

To restart manually:

docker compose restart print-bridge

Troubleshooting​

Container will not start​

docker compose logs print-bridge

Common causes:

  • BRIDGE_SECRET not set — add it to .env
  • Port already in use — change PORT in .env

Cannot reach the web UI​

  • Confirm the container is running: docker compose ps
  • Confirm port 3456 is not blocked by a firewall:
    • Windows: Allow port 3456 in Windows Defender Firewall
    • Linux: sudo ufw allow 3456
  • Try http://localhost:3456 from the same machine first

"Bridge is not paired" error on login page​

Pairing must be completed before you can sign in with a FlowPOS account. Click the → Go to Config link in the error message and complete pairing first (see Step 5.1).

Firebase login fails with "Cannot reach FlowPOS server"​

The bridge proxies Firebase authentication through the FlowPOS backend. Check:

  • The FLOWPOS_API_URL in Config is correct and reachable from the Print Bridge PC
  • The FlowPOS backend is running (curl <FLOWPOS_API_URL>/health)
  • If the network is down, use the Local password tab instead

Printers show "Disconnected"​

  • Verify the printer IP is reachable: ping <printer-ip>
  • Confirm the printer is powered on and on the same network
  • Check the printer's IP hasn't changed (assign a static IP or DHCP reservation)
  • For USB printers: verify the device path (/dev/ttyUSB0) exists inside the container

Agent shows "Not paired"​

The device token may have become invalid. Re-pair:

  1. Click Unpair on the Config page
  2. Generate a new pairing code in FlowPOS (Kitchen Stations → Pair Print Bridge)
  3. Enter the new code and pair again

Jobs show "pending" but nothing prints​

  1. Confirm the agent is running (Status page → Running)
  2. Try Test Print — if that fails, the issue is the printer connection
  3. Check logs: docker compose logs -f print-bridge
  4. On the Status page, use the Recovery options to re-print or discard stuck jobs

Emergency access (locked out)​

If Firebase is unavailable and no local password is set:

  1. Stop the container: docker compose stop print-bridge

  2. Generate a recovery token: openssl rand -hex 16

  3. Restart with the emergency token:

    BRIDGE_EMERGENCY_TOKEN=<your-token> docker compose up -d

  4. Open the UI and use the token as the local password — or use curl:

    curl -X POST http://localhost:3456/api/auth/local-password \
      -H "Authorization: Bearer <your-token>" \
      -H "Content-Type: application/json" \
      -d '{"password": "new-password"}'

  5. Remove BRIDGE_EMERGENCY_TOKEN from the environment and restart

Data and backups​

All configuration is stored in a Docker named volume (print-bridge-data). To back it up:

docker run --rm \
  -v print-bridge-data:/data \
  -v "$(pwd)":/backup \
  alpine tar czf /backup/print-bridge-data-$(date +%Y%m%d).tar.gz -C /data .

To restore:

docker compose down
docker run --rm \
  -v print-bridge-data:/data \
  -v "$(pwd)":/backup \
  alpine tar xzf /backup/print-bridge-data-YYYYMMDD.tar.gz -C /data
docker compose up -d

Quick reference​

ActionWhere
View printer statusStatus page → Printer rows
View recent print jobsStatus page → Recent Jobs
Add / edit printersPrinters page
Change API URL or timezoneConfig page
Pair or unpairConfig page
Start / stop the agentStatus page → Agent controls
Re-print a jobStatus page → Recent Jobs → Reprint
View container logsdocker compose logs -f print-bridge
Check API healthcurl http://localhost:3456/api/status