253 lines
13 KiB
HTML
253 lines
13 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="UTF-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
|
||
<title>FAQ · PearDock Docs</title>
|
||
<meta name="description" content="Frequently asked questions about PearDock: install, keys, Docker group, Pear, Gatekeeper, AGPL, upgrades." />
|
||
<meta name="keywords" content="PearDock FAQ, install, keys, Docker group, AGPL" />
|
||
<meta name="author" content="HoneyPeer, LLC" />
|
||
<meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1" />
|
||
<meta name="googlebot" content="index, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1" />
|
||
<meta name="theme-color" content="#2dd4bf" />
|
||
<meta name="color-scheme" content="dark light" />
|
||
<meta name="application-name" content="PearDock" />
|
||
<meta name="apple-mobile-web-app-title" content="PearDock" />
|
||
<meta name="apple-mobile-web-app-capable" content="yes" />
|
||
<meta name="mobile-web-app-capable" content="yes" />
|
||
<meta name="msapplication-TileColor" content="#2dd4bf" />
|
||
<meta name="msapplication-config" content="/assets/favicons/browserconfig.xml" />
|
||
<meta name="format-detection" content="telephone=no" />
|
||
<link rel="canonical" href="https://peardock.boats/docs/faq" />
|
||
<link rel="alternate" hreflang="en" href="https://peardock.boats/docs/faq" />
|
||
<link rel="alternate" hreflang="x-default" href="https://peardock.boats/docs/faq" />
|
||
|
||
<!-- Open Graph -->
|
||
<meta property="og:type" content="article" />
|
||
<meta property="og:site_name" content="PearDock" />
|
||
<meta property="og:locale" content="en_US" />
|
||
<meta property="og:url" content="https://peardock.boats/docs/faq" />
|
||
<meta property="og:title" content="FAQ · PearDock Docs" />
|
||
<meta property="og:description" content="Frequently asked questions about PearDock: install, keys, Docker group, Pear, Gatekeeper, AGPL, upgrades." />
|
||
<meta property="og:image" content="https://peardock.boats/assets/brand/og-image.png" />
|
||
<meta property="og:image:secure_url" content="https://peardock.boats/assets/brand/og-image.png" />
|
||
<meta property="og:image:type" content="image/png" />
|
||
<meta property="og:image:width" content="1200" />
|
||
<meta property="og:image:height" content="630" />
|
||
<meta property="og:image:alt" content="PearDock: decentralized Docker management on HyperDHT" />
|
||
|
||
<!-- Twitter / X -->
|
||
<meta name="twitter:card" content="summary_large_image" />
|
||
<meta name="twitter:title" content="FAQ · PearDock Docs" />
|
||
<meta name="twitter:description" content="Frequently asked questions about PearDock: install, keys, Docker group, Pear, Gatekeeper, AGPL, upgrades." />
|
||
<meta name="twitter:image" content="https://peardock.boats/assets/brand/twitter-card.png" />
|
||
<meta name="twitter:image:alt" content="PearDock: decentralized Docker management" />
|
||
|
||
<!-- Icons & PWA -->
|
||
<link rel="icon" href="/assets/favicons/favicon.ico" sizes="any" />
|
||
<link rel="icon" type="image/png" sizes="32x32" href="/assets/favicons/favicon-32x32.png" />
|
||
<link rel="icon" type="image/png" sizes="16x16" href="/assets/favicons/favicon-16x16.png" />
|
||
<link rel="icon" type="image/png" sizes="48x48" href="/assets/favicons/favicon-48x48.png" />
|
||
<link rel="apple-touch-icon" sizes="180x180" href="/assets/favicons/apple-touch-icon.png" />
|
||
<link rel="manifest" href="/assets/favicons/site.webmanifest" />
|
||
<link rel="mask-icon" href="/assets/logo/peardock-wordmark.svg" color="#2dd4bf" />
|
||
|
||
<!-- Article -->
|
||
<meta property="article:section" content="Documentation" />
|
||
<meta property="article:author" content="HoneyPeer, LLC" />
|
||
<meta property="article:publisher" content="HoneyPeer, LLC" />
|
||
|
||
<script type="application/ld+json">
|
||
{
|
||
"@context": "https://schema.org",
|
||
"@type": [
|
||
"WebPage",
|
||
"TechArticle"
|
||
],
|
||
"name": "FAQ \u00b7 PearDock Docs",
|
||
"description": "Frequently asked questions about PearDock: install, keys, Docker group, Pear, Gatekeeper, AGPL, upgrades.",
|
||
"url": "https://peardock.boats/docs/faq",
|
||
"isPartOf": {
|
||
"@type": "WebSite",
|
||
"name": "PearDock",
|
||
"url": "https://peardock.boats"
|
||
},
|
||
"publisher": {
|
||
"@type": "Organization",
|
||
"name": "HoneyPeer, LLC",
|
||
"url": "https://peardock.boats"
|
||
},
|
||
"inLanguage": "en-US",
|
||
"primaryImageOfPage": {
|
||
"@type": "ImageObject",
|
||
"url": "https://peardock.boats/assets/brand/og-image.png",
|
||
"width": 1200,
|
||
"height": 630
|
||
},
|
||
"headline": "FAQ \u00b7 PearDock Docs"
|
||
}
|
||
</script>
|
||
|
||
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
|
||
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
|
||
<link rel="stylesheet" href="/src/styles/global.css" />
|
||
<link rel="stylesheet" href="/src/styles/docs.css" />
|
||
</head>
|
||
<body>
|
||
<div class="bg-mesh" aria-hidden="true"></div>
|
||
<div data-nav data-prefix="../"></div>
|
||
|
||
<div class="docs-layout">
|
||
<aside class="docs-sidebar" data-docs-nav data-prefix="../"></aside>
|
||
<button type="button" class="docs-sidebar-toggle" aria-label="Docs menu">☰</button>
|
||
|
||
<article class="docs-main">
|
||
<h1>FAQ</h1>
|
||
<p class="docs-lead">Short answers to common questions.</p>
|
||
|
||
<h2>Do I need to open ports or set up VPN / remote access?</h2>
|
||
<p>
|
||
<strong>No.</strong> PearDock is peer-to-peer over HyperDHT. You share the server’s public key;
|
||
clients holepunch an encrypted connection. You do not open inbound firewall ports for Docker or the control UI,
|
||
expose <code>dockerd</code> to the internet, or maintain a permanent VPN just to run ops.
|
||
Optional Holesail tunnels reach published services the same way, still without punching host firewall holes.
|
||
</p>
|
||
|
||
<h2>How do I install PearDock?</h2>
|
||
<pre><code>curl -fsSL https://install.peardock.boats | bash</code></pre>
|
||
<p>
|
||
Interactive: choose <strong>server</strong> (Linux systemd) or <strong>client</strong> (desktop).
|
||
Non-interactive: <code>--server --yes</code> / <code>--client --yes</code>.
|
||
Details: <a href="/download">Download & install</a>.
|
||
</p>
|
||
|
||
<h2>What do I share with clients?</h2>
|
||
<ul>
|
||
<li><strong>Viewers:</strong> <code>SERVER_PUBLIC_KEY</code> only (64 hex) — read-only.</li>
|
||
<li><strong>Admins:</strong> public key + <code>SERVER_SEED</code> (from the same <code>.env</code>) — never send the seed over chat to operators.</li>
|
||
<li><strong>Operators:</strong> a full <code>pd1.…</code> invite from Access → Create invite (embeds key + capability; no seed).</li>
|
||
</ul>
|
||
<p>Never share <code>SERVER_SEED</code> with operators.</p>
|
||
|
||
<h2>Where are the public key and seed after install?</h2>
|
||
<p>
|
||
After the first successful start, both are written to
|
||
<code>/opt/peardock/.env</code>. <strong>Check that file:</strong>
|
||
</p>
|
||
<pre><code>sudo grep -E '^(SERVER_PUBLIC_KEY|SERVER_SEED)=' /opt/peardock/.env
|
||
# or: sudo cat /opt/peardock/.env
|
||
|
||
# Public key also appears in the journal
|
||
sudo journalctl -u peardock -n 80 --no-pager | grep -i 'public key'</code></pre>
|
||
<p>
|
||
<code>SERVER_PUBLIC_KEY</code> is safe to share for viewer access.
|
||
<code>SERVER_SEED</code> is admin-only. Keep <code>.env</code> mode 600 and back it up offline.
|
||
</p>
|
||
|
||
<h2>How do invites work?</h2>
|
||
<p>
|
||
As admin (public key + <code>SERVER_SEED</code> in Add peer), open <strong>Access → Create invite</strong>
|
||
and copy the full string starting with <code>pd1.</code>. The operator pastes that entire string in Add peer.
|
||
Public key and HMAC capability are embedded — no Autopass/RocksDB and no seed sharing.
|
||
Invites can be persistent (default) or limited by TTL / max uses. Revoke peers from Access when devices are lost.
|
||
Deep dive: <a href="/docs/security">Security model</a>.
|
||
</p>
|
||
|
||
<h2>Container list empty / “permission denied” on Docker</h2>
|
||
<p>The service user <code>peardock</code> needs the docker group:</p>
|
||
<pre><code>sudo usermod -aG docker peardock
|
||
sudo systemctl restart peardock
|
||
# if the group was just created:
|
||
sudo systemctl restart docker</code></pre>
|
||
<p>The one-line installer does this automatically on server install.</p>
|
||
|
||
<h2>Is there a cloud / SaaS component?</h2>
|
||
<p>No. HyperDHT holepunches between peers. Bootstrap nodes are part of the HyperDHT network; PearDock does not operate a proprietary control plane.</p>
|
||
|
||
<h2>Pear prints “DEPRECATED: pear run is deprecated”</h2>
|
||
<p>Platform-wide message. Prefer the Electron desktop client from the rolling release or <code>install.sh --client</code>. Source: <code>npm run start:client</code>.</p>
|
||
|
||
<h2>macOS says the app is damaged</h2>
|
||
<p>Usually quarantine or signature after download. Installer runs <code>xattr -cr</code>. Manually:</p>
|
||
<pre><code>xattr -cr ~/Applications/peardock.app
|
||
# or right-click → Open
|
||
# re-sign from source build:
|
||
npm run sign:macos -- out/peardock-darwin-arm64/peardock.app</code></pre>
|
||
|
||
<h2>Client lost connection. Does it reconnect?</h2>
|
||
<p>Yes. Unexpected disconnects retry every <strong>5 seconds</strong> until the peer is back or you remove it. Last active peer is restored on launch.</p>
|
||
|
||
<h2>Why is PearDock AGPL?</h2>
|
||
<p>PearDock is <strong>AGPL-3.0</strong>, matching Holesail (also AGPL-3.0). If you modify PearDock and let others use it over a network, review AGPL source-offer obligations. You can set <code>ENABLE_HOLESAIL=0</code> to disable tunnel creation.</p>
|
||
|
||
<h2>Can I run without Holesail?</h2>
|
||
<p>Yes: <code>ENABLE_HOLESAIL=0</code> in the server environment. Control-plane Docker management still works.</p>
|
||
|
||
<h2>Default role is viewer. How do I get admin?</h2>
|
||
<p>
|
||
Public key alone is <strong>viewer</strong> (read-only). For admin, paste
|
||
<code>SERVER_PUBLIC_KEY</code> + <code>SERVER_SEED</code> from <code>/opt/peardock/.env</code>
|
||
in Add peer. For multi-operator fleets, create <code>pd1.</code> invites instead of sharing the seed.
|
||
Optional: <code>PEARDOCK_ADMIN_KEYS</code>, allowlist. See <a href="/docs/security">threat model</a>.
|
||
</p>
|
||
|
||
<h2>v1 vs v2</h2>
|
||
<p>v1 used Hyperswarm topics and raw JSON streams. v2 uses HyperDHT keypairs, public keys, and protomux-rpc. Clients and servers are not wire-compatible across major versions.</p>
|
||
|
||
<h2>Where is peer state stored on the client?</h2>
|
||
<p>Typically <code>~/.config/peardock/cache/peers.json</code> (includes last active peer id).</p>
|
||
|
||
<h2>Where do I store registry credentials?</h2>
|
||
<p>
|
||
In the desktop app open the top-level <strong>Registry</strong> view (not Access).
|
||
Vault credentials are encrypted on the server in <code>peardock-vault.json</code>
|
||
(AES-GCM from <code>SERVER_SEED</code>). From Registry you can also search Docker Hub,
|
||
browse remote catalogs/tags/manifests, and pull with a selected credential.
|
||
Pull/push from the <strong>Images</strong> view can use the same vault entries.
|
||
</p>
|
||
|
||
<h2>Where did Peers go? Where are saved hosts?</h2>
|
||
<p>
|
||
<strong>Settings → Peers</strong> manages client-side saved hosts (public keys, aliases).
|
||
Server-side ACL — invites, revoke, roles — stays under <strong>Access</strong>.
|
||
</p>
|
||
|
||
<h2>What does the Updates column on containers mean?</h2>
|
||
<p>
|
||
PearDock compares each container’s local image <code>RepoDigest</code> to the remote registry
|
||
manifest for the same tag. Green = up to date, orange = update available (click to pull),
|
||
grey = unknown/skipped. <strong>Check updates</strong> in the containers action bar forces a
|
||
recheck and reports in the job tray. Private registries use vault credentials.
|
||
Server caches digests for about five minutes. RPC: <code>checkImageUpdates</code>.
|
||
</p>
|
||
|
||
<h2>How do long image pulls show progress?</h2>
|
||
<p>
|
||
Pull and push stream layer events over <code>push:pullProgress</code> /
|
||
<code>push:pushProgress</code>. The desktop job tray aggregates them into hybrid overall
|
||
progress, phase labels, and a fixed-height layer track — not a single misleading percentage.
|
||
</p>
|
||
|
||
<h2>How do I update?</h2>
|
||
<ul>
|
||
<li><strong>Server:</strong> re-run <code>install.sh --server --yes</code> or replace the binary; keep <code>/opt/peardock/.env</code>; <code>systemctl restart peardock</code>.</li>
|
||
<li><strong>Client:</strong> re-run <code>install.sh --client --yes</code> or install a newer rolling tarball.</li>
|
||
<li><strong>Assets:</strong> <a href="https://git.ssh.surf/snxraven/peardock/releases/tag/rolling" target="_blank" rel="noopener">rolling</a> tag on every main CI build.</li>
|
||
</ul>
|
||
|
||
<h2>License</h2>
|
||
<p>PearDock and Holesail: <strong>AGPL-3.0</strong>. See <a href="/legal/license">Open Source Notices</a>.</p>
|
||
|
||
<div class="docs-pager">
|
||
<a href="/docs/release"><span>Previous</span><strong>← Releases</strong></a>
|
||
<a class="next" href="/docs/index"><span>Docs home</span><strong>Overview →</strong></a>
|
||
</div>
|
||
</article>
|
||
</div>
|
||
|
||
<div data-footer data-prefix="../"></div>
|
||
<script type="module" src="/src/js/site.js"></script>
|
||
</body>
|
||
</html>
|