docs(catalog): audit and fix 10 hallucinations in install guides
Round-1 docs claimed things the code does not do. This commit rewrites
all 77 per-template pages + the catalog index to match reality:
CORRECTED:
- REST API payload shape: was {template, subdomain, port, environment}
Real Joi schema (src/utilities/validate.js appDeploy) is
{appId, config: {subdomain, port, mediaPath?, plexClaimToken?, ...}}
All optional fields now documented per-schema.
- Auth methods: was just "Authorization: Bearer" — real middleware
accepts three (TOTP session cookie, Authorization: Bearer JWT,
X-API-Key header). All three now shown.
- Deploy is synchronous: was "poll GET /api/v1/apps/{id}/status" — there
is no status endpoint. Response shape documented as
{success, containerId, url, message, setupInstructions}.
- AI Intent Router: was "starts the deployment" — it returns a
structured intent; the caller must POST /api/v1/apps/deploy to
actually provision. Documented accurately.
- MCP dashcaddy_deploy_app: was treated as full deploy — it only writes
the Caddy route + services.json entry, NOT the container. Documented
as such with manual docker pull as next step.
- Watchtower: was claimed to auto-update every 24h — DashCaddy does NOT
poll for new digests. Watchtower is a separate template with default
schedule 0 0 4 * * * (cron 04:00). Documented.
- Update button: was "Apps → {Name} → Update" — no such endpoint exists.
Manual docker pull + restart now documented.
- Restore-on-install: was "prompt to restore from snapshot during install"
— no such prompt. POST /api/v1/apps/{appId}/restore documented.
- Backups: was "default daily snapshot" — backup schedule is
configurable via backup-config.json, not "nightly" by default.
Volumes ARE included; documented.
- Dashboard menu: was "Apps → Catalog" — actual entry is the
"App Selector" button on the dashboard home. Documented.
- Dashboard URL: status.sami confirmed correct (configurable via
dashboardHost).
Also fixes default port resolution: was using portList[0].split(":")[0]
which leaks "{{PORT}}" literal when the template uses the placeholder.
Now uses t.defaultPort (Joi-validated) first, falling back to portList.
Build: 78 routes prerender as static, TypeScript clean.
This commit is contained in:
78 files changed
+7274
-7395
No files matched your search
@@ -16,117 +16,115 @@ export default function piholeDocsPage() {
|
||||
intro="Network-wide ad blocker and DNS sinkhole"
|
||||
>
|
||||
<div className="mb-6 flex flex-wrap gap-3 text-xs font-semibold">
|
||||
<span className="rounded-full bg-surface-800 px-3 py-1 text-surface-300">Category: Networking</span>
|
||||
<span className="rounded-full px-3 py-1" style={{ backgroundColor: '#68a4ff22', color: '#68a4ff' }}>Difficulty: Intermediate</span>
|
||||
<span className="rounded-full bg-surface-800 px-3 py-1 text-surface-300">Docker image: <code className="text-brand-400">pihole/pihole:latest</code></span>
|
||||
</div>
|
||||
<span className="rounded-full bg-surface-800 px-3 py-1 text-surface-300">Category: Networking</span>
|
||||
<span className="rounded-full px-3 py-1" style={{ backgroundColor: '#68a4ff22', color: '#68a4ff' }}>Difficulty: Intermediate</span>
|
||||
<span className="rounded-full bg-surface-800 px-3 py-1 text-surface-300">Docker image: <code className="text-brand-400">pihole/pihole:latest</code></span>
|
||||
</div>
|
||||
|
||||
<h2>What is Pi-hole?</h2>
|
||||
<p>Network-wide ad blocker and DNS sinkhole</p>
|
||||
<p>Pi-hole ships as a self-contained Docker image that DashCaddy provisions with one click. The platform handles the container lifecycle, DNS, reverse proxy, HTTPS certificate, and persistent storage so you can focus on using Pi-hole, not installing it.</p>
|
||||
<h2>What is Pi-hole?</h2>
|
||||
<p>Network-wide ad blocker and DNS sinkhole</p>
|
||||
<p>Pi-hole ships as a self-contained Docker image that DashCaddy provisions with one click. DashCaddy handles the container lifecycle, DNS record, Caddy reverse-proxy entry, and HTTPS certificate so you can focus on using Pi-hole, not installing it.</p>
|
||||
|
||||
<h2>Prerequisites</h2>
|
||||
<ul>
|
||||
<li>A running DashCaddy host with the dashboard accessible.</li>
|
||||
<li>No special host paths required.</li>
|
||||
|
||||
<li>If you want a stable subdomain: Technitium DNS recommended (otherwise DashCaddy will use direct IP access).</li>
|
||||
</ul>
|
||||
<h2>Prerequisites</h2>
|
||||
<ul>
|
||||
<li>A running DashCaddy host with the dashboard accessible (default URL: <code>https://status.sami</code>; configurable via the <code>dashboardHost</code> setting in <code>config.json</code>).</li>
|
||||
<li>You must be signed in to the dashboard with an admin session, or have an API key with admin scope (<code>POST /api/v1/auth/keys</code> to create one).</li>
|
||||
<li>No special host paths required.</li>
|
||||
<li>For HTTPS with a real certificate, Technitium DNS must be configured and the host must have port 80/443 reachable from the internet. Otherwise DashCaddy will fall back to direct-IP access or a self-signed certificate.</li>
|
||||
</ul>
|
||||
|
||||
<h2>Install via the DashCaddy dashboard</h2>
|
||||
<ol>
|
||||
<li>Sign in at <code>https://status.sami</code> (or your host's dashboard URL).</li>
|
||||
<li>Open <strong>Apps → Catalog</strong> and select <strong>Pi-hole</strong> from the <em>Networking</em> category.</li>
|
||||
<li>Choose your host (or pick <em>Local</em> if you have one host).</li>
|
||||
<li>Fill in any required fields (notably the media library path and any claim token).</li>
|
||||
<li>Click <strong>Deploy</strong>. DashCaddy will:
|
||||
<ol>
|
||||
<li>Pull the <code>pihole/pihole:latest</code> image.</li>
|
||||
<li>Create persistent volumes for config and data.</li>
|
||||
<li>Reserve a host port and wire it through Caddy.</li>
|
||||
<li>Issue a Let's Encrypt certificate for <code>pihole.<your-domain></code>.</li>
|
||||
<li>Wait for the container health check (<code>/admin/</code>) to pass.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>After ~30–60 seconds the dashboard will turn the row <strong>Running</strong> and the URL will become clickable.</li>
|
||||
</ol>
|
||||
<h2>Install via the DashCaddy dashboard</h2>
|
||||
<ol>
|
||||
<li>Sign in at <code>https://status.sami</code> (or your host's dashboard URL).</li>
|
||||
<li>Click the <strong>📱 App Selector</strong> button on the dashboard home page.</li>
|
||||
<li>Pick <strong>Pi-hole</strong> from the Networking category.</li>
|
||||
<li>Fill in the deployment form: subdomain (default suggestion: <code>pihole</code>), host port (default: <code>80</code>).</li>
|
||||
<li>Click <strong>Deploy</strong>. DashCaddy will pull the image, create persistent volumes, write a Caddy route, create the DNS record, and wait up to 30 seconds for the container's health check (<code>/admin/</code>) to pass.</li>
|
||||
<li>When the dashboard shows the service as <strong>Running</strong>, the URL (built from your subdomain and configured TLD) is clickable. The deploy API returns a synchronous response with <code>{success, containerId, url, message, setupInstructions}</code> — there is no separate status-poll endpoint; the dashboard updates live.</li>
|
||||
</ol>
|
||||
|
||||
<h2>Install via the REST API</h2>
|
||||
<p>If you script deployments or use the MCP / AI Intent Router, install with:</p>
|
||||
<pre className="overflow-x-auto rounded-lg bg-surface-900 p-4 text-sm"><code>curl -X POST https://your-dashcaddy-host/api/v1/apps/deploy \\
|
||||
-H "Authorization: Bearer $DASHCADDY_API_TOKEN" \\
|
||||
<h2>Install via the REST API</h2>
|
||||
<p>Authenticate with an API key (or a JWT minted via <code>POST /api/v1/auth/jwt</code>). Send as <code>X-API-Key: dk_...</code> or <code>Authorization: Bearer <jwt></code>.</p>
|
||||
<pre className="overflow-x-auto rounded-lg bg-surface-900 p-4 text-sm"><code>curl -X POST https://status.sami/api/v1/apps/deploy \\
|
||||
-H "X-API-Key: dk_your_api_key" \\
|
||||
-H "Content-Type: application/json" \\
|
||||
-d '{
|
||||
"template": "pihole",
|
||||
"host": "local",
|
||||
"subdomain": "pihole",
|
||||
"port": "{{PORT}}",
|
||||
"environment": {
|
||||
"WEBPASSWORD": "",
|
||||
"TZ": ""
|
||||
},
|
||||
"labels": { "managed-by": "dashcaddy" }
|
||||
"appId": "pihole",
|
||||
"config": {
|
||||
"subdomain": "pihole",
|
||||
"port": 80
|
||||
}
|
||||
}'</code></pre>
|
||||
<p>Response returns a deployment ID. Poll <code>GET /api/v1/apps/{id}/status</code> until <code>state === "running"</code>.</p>
|
||||
<p>The full body schema is in <code>src/utilities/validate.js</code> (Joi schema <code>appDeploy</code>). All <code>config.*</code> fields except <code>subdomain</code> are optional. Notable options:</p>
|
||||
<ul>
|
||||
<li><code>config.port</code> — host port (1–65535). Defaults to the template's <code>defaultPort</code>.</li>
|
||||
<li><code>config.mediaPath</code> — host directory to mount as the media library.</li>
|
||||
<li><code>config.plexClaimToken</code> — Plex claim token (when the upstream service needs one).</li>
|
||||
<li><code>config.useExisting: true</code> + <code>existingContainerId</code> — attach DashCaddy metadata to an already-running container instead of pulling a new image.</li>
|
||||
<li><code>config.tailscaleOnly: true</code> — restrict the reverse-proxy entry to your Tailscale network.</li>
|
||||
<li><code>config.allowedIPs</code> — array of CIDR ranges allowed past the reverse proxy.</li>
|
||||
<li><code>config.createDns: false</code> — skip DNS record creation (use when the subdomain already resolves).</li>
|
||||
<li><code>config.resources</code> — <code>{memory, cpus}</code> limits applied to the container.</li>
|
||||
</ul>
|
||||
|
||||
<h2>Install via the AI Intent Router</h2>
|
||||
<p>From any chat surface wired to DashCaddy's MCP server, just say:</p>
|
||||
<blockquote className="border-l-4 border-brand-500/50 bg-brand-500/5 p-4 rounded-r-lg">
|
||||
<p className="text-surface-300">"Deploy Pi-hole on my home host and expose it at <code>pihole.sami</code>"</p>
|
||||
</blockquote>
|
||||
<p>The Intent Router will pick the right template, prompt you for any missing fields, and start the deployment.</p>
|
||||
<h2>Install via the AI Intent Router (returns a structured intent)</h2>
|
||||
<p>The Intent Router returns a structured intent, not a deployed container. To deploy via AI, send natural language to:</p>
|
||||
<pre className="overflow-x-auto rounded-lg bg-surface-900 p-4 text-sm"><code>curl -X POST https://status.sami/api/v1/ai/intent \\
|
||||
-H "X-API-Key: dk_your_api_key" \\
|
||||
-H "Content-Type: application/json" \\
|
||||
-d '{ "message": "Deploy Pi-hole on my home host and expose it at pihole.sami" }'</code></pre>
|
||||
<p>The response includes <code>intent</code>, <code>action</code>, <code>parameters</code>, and <code>followup</code> — your client (or the MCP server) must then call <code>POST /api/v1/apps/deploy</code> with those parameters to actually provision the container.</p>
|
||||
|
||||
<h2>Post-install: first-run checklist</h2>
|
||||
<ol>
|
||||
<li>Open the new <code>pihole.<your-domain></code> URL.</li>
|
||||
<li>Complete the upstream Pi-hole setup wizard (create admin user, accept EULA, etc.).</li>
|
||||
<li>Configure backups from <strong>Settings → Backups</strong> — the default daily snapshot will capture the data volume.</li>
|
||||
</ol>
|
||||
<h2>Install via the MCP Server</h2>
|
||||
<p>For AI agents (Claude Desktop, Hermes, etc.) configure the MCP server (<code>src/mcp/mcp-server.js</code>) with:</p>
|
||||
<pre className="overflow-x-auto rounded-lg bg-surface-900 p-4 text-sm"><code>DASHCADDY_URL=https://status.sami:3001 # internal API URL, may differ from dashboard URL
|
||||
DASHCADDY_API_KEY=dk_your_api_key</code></pre>
|
||||
<p>The server exposes <code>dashcaddy_deploy_app</code>. Note: this tool writes the Caddy route and creates the <code>services.json</code> entry, but it does NOT pull the Docker image or start the container. You must run <code>docker pull pihole/pihole:latest</code> and start the container yourself for the URL to actually serve traffic. For a fully-managed deployment, call <code>POST /api/v1/apps/deploy</code> directly from your agent.</p>
|
||||
|
||||
<h2>Post-install: first-run checklist</h2>
|
||||
<ol>
|
||||
<li>Open the deployed URL (returned in the response as <code>url</code>, or visible in the dashboard).</li>
|
||||
<li>Complete the upstream Pi-hole setup wizard (admin account, library paths, EULA).</li>
|
||||
<li>Restore from a backup if one exists: <code>POST /api/v1/apps/{appId}/restore</code> with the backup ID from <code>GET /api/v1/backups/history</code>.</li>
|
||||
</ol>
|
||||
<h2>Volumes and persistent data</h2>
|
||||
<p>DashCaddy creates these volume mounts in the container spec:</p>
|
||||
<ul>
|
||||
<li><code>/opt/pihole/etc:/etc/pihole</code></li>
|
||||
<li><code>/opt/pihole/dnsmasq:/etc/dnsmasq.d</code></li>
|
||||
</ul>
|
||||
<p>All paths are host paths (left side) mapped into the container (right side). Restarting the container preserves data; reinstalling the template preserves it unless you explicitly pass <code>config.useExisting: false</code> AND wipe the volume. Bind mounts use the host-path conventions above (e.g. <code>/opt/plex/config</code> becomes a bind mount to the host directory of the same path).</p>
|
||||
|
||||
<h2>Environment variables</h2>
|
||||
<ul>
|
||||
<li><code>WEBPASSWORD</code></li>
|
||||
<li><code>TZ</code></li>
|
||||
</ul><p>These are baked into the template at deploy time and shipped to the container. The deploy handler does NOT allow overriding them via the API payload — to change them you must edit the template definition in <code>dashcaddy-api/src/docker/app-templates.js</code>.</p>
|
||||
|
||||
<h2>Volumes and persistent data</h2>
|
||||
<p>DashCaddy creates these volume mounts:</p>
|
||||
<ul>
|
||||
<li><code>/opt/pihole/etc:/etc/pihole</code></li>
|
||||
<li><code>/opt/pihole/dnsmasq:/etc/dnsmasq.d</code></li>
|
||||
</ul>
|
||||
<p>All paths are absolute host paths; the left side is the container-side mount. Restarting the container never deletes the data; reinstalling the template preserves it unless you explicitly check <em>Wipe data</em> on the deploy form.</p>
|
||||
<h2>Updating the image</h2>
|
||||
<p>There is no built-in auto-update — DashCaddy does NOT poll for new image digests. To pull a new version:</p>
|
||||
<ol>
|
||||
<li>SSH into the DashCaddy host and run <code>docker pull pihole/pihole:latest</code>.</li>
|
||||
<li>Restart the container: <code>docker restart <containerId></code> (find the ID via <code>GET /api/v1/services</code> or the dashboard).</li>
|
||||
<li>Or deploy Watchtower from this catalog (separate template that polls Docker Hub and updates other containers automatically, default schedule <code>0 0 4 * * *</code> = 04:00 daily).</li>
|
||||
</ol>
|
||||
|
||||
<h2>Environment variables</h2>
|
||||
<ul><li><code>WEBPASSWORD</code></li>
|
||||
<li><code>TZ</code></li></ul>
|
||||
<p>Override any of these from the deploy form's <em>Environment</em> panel, or programmatically in the API <code>environment</code> object.</p>
|
||||
<h2>Backups</h2>
|
||||
<p>The default backup policy includes the entire <code>/app/data/</code> directory (services, config, credentials, stats) AND all Docker volumes. Backups are scheduled via <code>backup-config.json</code> — the default schedule is configurable, not "nightly" out of the box. To restore on a fresh host, redeploy the same template and then call <code>POST /api/v1/apps/{appId}/restore</code> with a backup ID from <code>GET /api/v1/backups/history</code>.</p>
|
||||
|
||||
<h2>Updating</h2>
|
||||
<p>DashCaddy's built-in Watchtower integration will pull <code>pihole/pihole:latest</code> every 24 hours and restart your container with zero downtime if the image digest changes. To force an update immediately, click <strong>Apps → Pi-hole → Update</strong>.</p>
|
||||
|
||||
<h2>Backups</h2>
|
||||
<p>The config volume for Pi-hole is included in DashCaddy's default nightly snapshot. To restore on a fresh host, redeploy the same template and DashCaddy will prompt to restore from the most recent snapshot during install.</p>
|
||||
|
||||
<h2>Troubleshooting</h2>
|
||||
<p>Common issues with Pi-hole:</p>
|
||||
<ul>
|
||||
<li><strong>Container won't start:</strong> check the dashboard's <em>Logs</em> tab. Most startup failures are permission errors on the media/config volume.</li>
|
||||
|
||||
|
||||
<li><strong>Slow first scan:</strong> expected for large libraries on first run. Subsequent restarts are fast.</li>
|
||||
</ul>
|
||||
<p>For layer-by-layer diagnostics, see the <a href="/docs/troubleshooting" className="text-brand-400 underline">Troubleshooting guide</a>.</p>
|
||||
|
||||
<h2>Related services</h2>
|
||||
<p>Pi-hole is in the <strong>Networking</strong> category. Common pairings:</p>
|
||||
<ul>
|
||||
<li><a href="/docs/catalog/technitium" className="text-brand-400 underline">Technitium DNS</a> (more powerful DNS)</li>
|
||||
<li><a href="/docs/catalog/wireguard" className="text-brand-400 underline">WireGuard</a> (private DNS over VPN)</li>
|
||||
</ul>
|
||||
|
||||
<hr className="my-8 border-surface-700" />
|
||||
<p className="text-sm text-surface-400">
|
||||
Last reviewed against DashCaddy product version in <code>dashcaddy-api/src/docker/app-templates.js</code>.
|
||||
Template ID: <code>pihole</code>. If anything here looks wrong, edit the file and the change will appear in the next docs rebuild.
|
||||
</p>
|
||||
<h2>Troubleshooting</h2>
|
||||
<p>Common issues with Pi-hole:</p>
|
||||
<ul>
|
||||
<li><strong>Container won't start:</strong> check the dashboard's Logs panel. Most startup failures are permission errors on the host-path volume.</li>
|
||||
<li><strong>URL not reachable after deploy:</strong> the Caddy route was written but DNS hasn't propagated, or port 80/443 is firewalled. Check <code>GET /api/v1/dns/records</code> and <code>systemctl status caddy</code> on the host.</li>
|
||||
<li><strong>Health check timeout (deploy returns 30s after start):</strong> the container is starting but <code>/admin/</code> is not returning 200. Inspect <code>docker logs <containerId></code> directly.</li>
|
||||
</ul>
|
||||
<p>For layer-by-layer diagnostics, see the <a href="/docs/troubleshooting" className="text-brand-400 underline">Troubleshooting guide</a>.</p>
|
||||
|
||||
<hr className="my-8 border-surface-700" />
|
||||
<p className="text-sm text-surface-400">
|
||||
Template ID: <code>pihole</code>. Source: <code>dashcaddy-api/src/docker/app-templates.js</code>.
|
||||
</p>
|
||||
</DocsLayout>
|
||||
<Footer />
|
||||
</div>
|
||||
|
||||
Reference in new issue
Block a user