peardock/README.md

peardock

Decentralized Docker management on the modern Holepunch stack.

Layer	Technology
Transport	HyperDHT (Noise-encrypted P2P)
RPC	protomux-rpc + compact-encoding JSON
Client	Pear desktop app
Docker	dockerode

No central control plane. The server announces a keypair on the DHT; clients connect with its public key.

---

Quick start

1. Install

npm install
# Node.js ≥ 20 required

2. Run the server (machine with Docker)

npm run server

You will see:

  peardock server ready
  Public key (paste into the client):
  <64 hex characters>

Keep this process running. Identity is stored in .env:

Variable	Meaning
SERVER_SEED	Secret 32-byte seed (never share)
SERVER_PUBLIC_KEY	Derived public key (share with clients)
SERVER_KEY	Legacy alias for the seed (still accepted)

3. Run the desktop client

Ensure the Pear binary is on your PATH (one-time):

# macOS
export PATH="$HOME/Library/Application Support/pear/bin:$PATH"
# make permanent in fish:
# fish_add_path "$HOME/Library/Application Support/pear/bin"

Then:

npm run dev
# or: pear run -d .

Paste the public key into the sidebar connection field.

Note: Pear may print DEPRECATED: pear run is deprecated. That is a platform-wide message. This app uses the supported pear-electron + pear-bridge entry (index.js) so it is not a legacy HTML app. Long-term OTA packaging uses hello-pear-electron / pear-runtime.

Production Pear app

pear stage .
pear release .
pear run pear://<your-app-key>

---

Architecture

shared/           Protocol constants + encodings (both sides)
server/
  server.js       Entry: HyperDHT listen
  core/           Keys, peer registry
  rpc/            PeerSession (protomux-rpc), handler registration
  handlers/       Domain methods (containers, images, volumes, …)
  services/       Docker client, stats, event stream
  utils/          Validation, rate limit, logging, compose
client/
  connection.js   Single HyperDHT + protomux-rpc link
  manager.js      Multi-server connections + persistence
  api.js          Typed RPC helpers
app.js + libs/    Pear UI

RPC model

Client → server methods (examples): handshake, ping, listContainers, killContainer, containerTop, deployContainer, pruneImages, getSystemDf, startTerminal, …

Server → client pushes: push:containers, push:allStats, push:logs, push:pullProgress, push:buildProgress, push:dockerEvent, push:terminalOutput, …

Defined in shared/protocol.js (PROTOCOL_VERSION negotiated on connect). See ROADMAP.md for coverage and remaining work.

---

Deployment

1. Host — Linux/macOS with Docker socket access for the server user.
2. Process — systemd / pm2 / Docker supervising node server/server.js.
3. Network — HyperDHT holepunches; allow UDP when possible. Bootstrap peers are built into hyperdht.
4. Secrets — Back up SERVER_SEED. Rotating seed changes the public key; clients must reconnect.
5. Pear — Stage/release the desktop app separately from the control-plane server.
6. Security — Connections are E2E encrypted (Noise). Rate limits apply per peer. RPC methods are gated by role (viewer / operator / admin; default admin). Privileged actions append to an audit log. Docker CLI is allow-listed to read-only style commands. Optional env: PEARDOCK_DEFAULT_ROLE, PEARDOCK_ADMIN_KEYS, PEARDOCK_BROWSE_ROOTS, PEARDOCK_AUDIT.
7. Holesail tunnels (on by default) — Expose published container/host ports over Holesail hs:// keys (separate from control-plane RPC). Opt out with ENABLE_HOLESAIL=0. See docs/HOLESAIL.md. Note: the required holesail dependency is AGPL-3.0.

Example systemd unit:

[Unit]
Description=peardock HyperDHT server
After=docker.service
Requires=docker.service

[Service]
WorkingDirectory=/opt/peardock
ExecStart=/usr/bin/node server/server.js
Restart=on-failure
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

---

Scripts

Command	Description
npm run server	Start HyperDHT Docker control plane
npm run dev	Pear desktop app (dev)
npm test	Unit + fuzz + load + integration tests
npm run healthcheck	Docker socket health probe
npm run soak / soak:24h	Certification soak against Docker
npm run release:checksums	Release tarball + SHA-256 (+ optional GPG)

See ROADMAP.md (complete) and docs/ for operators, threat model, and releases.

---

Dependencies (current)

• hyperdht ^6.33
• protomux-rpc ^1.10
• protomux ^3.11
• compact-encoding ^3.3
• b4a ^1.8
• hypercore-crypto ^3.7
• dockerode ^5
• dotenv ^17
• graceful-goodbye ^1.3

---

Breaking changes from v1

v1 (legacy)	v2 (current)
Hyperswarm topic = SERVER_KEY	HyperDHT listen on keypair from seed
Share topic hex with clients	Share public key with clients
Raw JSON on duplex streams	protomux-rpc methods + push channels
Monolithic server.js switch	Modular handlers under server/handlers/

---

License

Apache-2.0