Deployment Topologies

Deployment Topologies

Pizarra 1.1.41 uses one authoritative hub. Start with a loopback installation, then add remote hosts only after the identity, account, and network boundaries are understood.

Choose a delivery mode

Pattern	Inbound network path	Credential on team host	Best fit
Local session	Hub loopback only	No remote credential	One control host
Reverse dial	Endpoint daemon connects to hub	Bound team credential	Preferred remote mode, NAT, changing address
Direct push	Hub connects to daemon	Hub master credential	Only a tightly trusted private host
Inbox only	Client connects to hub	Bound identity credential	No managed terminal session

Default ports are 7010 for the hub, 7011 for a direct-push daemon, and 7080 for pzweb. They are configurable. The protocols are cleartext and require an independent encrypted network boundary between hosts.

Topology A: one loopback control host

flowchart LR
    C[tiza chat] --> P[pizarra 127.0.0.1:7010]
    W[pzweb 127.0.0.1:7080] --> P
    P --> B[builder tmux]
    P --> T[tester tmux]

Loading

Use this first. The hub manages local named sessions under a dedicated account. pzweb still needs its own operating-system account and a separate team-bound credential if it is enabled.

Create the hub-side record through the console identity; it is committed to /var/lib/pizarra/org.sqlite, not duplicated in pizarra.conf:

tiza team add builder "Implements and verifies assigned work" \
  --session pizarra-builder --launch '<interactive-terminal-program>'
tiza team set builder workdir /srv/projects/atlas
tiza team set builder secret --file /run/secrets/pizarra-builder

Install the same owner-only secret in the builder identity file below /etc/pizarra/agents/. The path under /run/secrets is illustrative and must name a private file supplied by the operator.

The hub recreates a missing declared session. Removing the declaration does not kill an existing session.

Topology B: preferred reverse dial

flowchart RL
    D[tiza daemon on remote host] -->|outbound authenticated channel| P[pizarra hub]
    D --> R[reviewer tmux]

Loading

Create an inbox-only record first, bind its credential, and then select reverse dial. This avoids briefly creating a local terminal target during setup:

tiza team add reviewer "Independent review and verification" --session -
tiza team set reviewer secret --file /run/secrets/pizarra-reviewer
tiza team set reviewer dial on

Remote endpoint:

[pizarra]
host = 10.0.0.10
port = 7010
secret = <unique-reviewer-secret>
self = reviewer

[daemon]
dial = on
state = /var/lib/pizarra/tiza.state

[session:reviewer]
tmux_session = pizarra-reviewer
launch = <interactive-terminal-program>
workdir = /srv/reviewer/atlas

Benefits:

• no inbound daemon listener on the team host;
• no hub master credential on that host;
• NAT and changing endpoint addresses are easier;
• reconnection is automatic; and
• durable receipt state prevents duplicate terminal paste after restart.

Only one active reverse channel can serve a team at a time.

Topology C: direct push

Create the authoritative push target through the hub:

tiza team add reviewer "Independent review and verification" \
  --remote 10.0.0.42:7011
tiza team set reviewer secret --file /run/secrets/pizarra-reviewer

Remote daemon:

[pizarra]
host = 10.0.0.10
port = 7010
secret = <unique-reviewer-secret>
self = reviewer

[daemon]
listen = 10.0.0.42
port = 7011
secret = <hub-master-secret>
state = /var/lib/pizarra/tiza.state

The pushed deliver request currently authenticates with the hub master credential. A compromised direct-push host can therefore expose the master. Do not place that master value in a team slot, and do not use direct push when reverse dial is sufficient.

Firewall the daemon port to the exact hub address.

Topology D: inbox only

tiza team add audit-view "Reads scoped operational messages" --session -
tiza team set audit-view secret --file /run/secrets/pizarra-audit-view

No terminal session or remote delivery exists. The identity reads its durable queue through Tiza. This is useful for integrations and narrowly scoped observers.

Separate service accounts

A secure same-host layout uses distinct accounts:

Account	May read	Must not read
pizarra	Hub config, hub store, hub log, its local sessions	Unrelated user data
tiza	Endpoint config, receipt state, its own sessions	Hub master config and store
pzweb	Web config, static assets, narrow optional shared paths	Hub config, hub store, hub user's tmux server

Example locations:

/etc/pizarra/pizarra.conf
/var/lib/pizarra/
/var/lib/pizarra/releases/
/var/log/pizarra/

/etc/pizarra/tiza.conf
/var/lib/pizarra/tiza.state

/etc/pizarra/pzweb.conf
/usr/local/share/pizarra/web/apps/

# Optional external/NFS exchange; configure this exact mount in hub and pzweb.
/mnt/pizarra-shared/

All real configs and state belong outside the source checkout. The optional shared mount also remains outside /var/lib/pizarra; migration, retirement, and built-in backup/restore do not move or copy its content.

Start order

1. hub;
2. remote endpoint daemons;
3. pzweb;
4. human consoles.

A daemon can start first and reconnect later. pzweb deliberately refuses to start unless it can prove its bound identity and delegated capabilities.

Network rules

• Bind to loopback or an explicit private address, never a wildcard by habit.
• Permit only exact peers through host firewalls.
• Prefer reverse dial.
• Add a private encrypted overlay or local encrypted tunnel across machines.
• Never expose ports 7010, 7011, or 7080 directly to the public Internet.
• Do not assume an ordinary HTTP reverse proxy is compatible with pzweb's exact direct-HTTP Host and Origin model.

Continue with Security Model, Configuration Reference, and Operations Runbook.