docs(catalog): add full install guides for all 77 app templates
Generate one dedicated install page per template in /docs/catalog/<id>/. Each page covers: - Prerequisites (with claim-token reminders where applicable) - Three install paths: dashboard UI, REST API (with curl), AI Intent Router - Post-install first-run checklist (from the template metadata) - Volume mounts and persistent data - Environment variables - Watchtower auto-update behavior - Backup inclusion - Common troubleshooting - Related services (category-aware cross-links) Also add /docs/catalog index page grouping all 77 templates by 17 categories, with difficulty badges and popularity-sorted entries. Sidebar updated to show the new App Catalog entry. Generated by /tmp/generate-template-docs.js (run from /opt/dashcaddy in a follow-up to keep content in sync with app-templates.js).
This commit is contained in:
Hermes
@@ -0,0 +1,142 @@
|
||||
import Navbar from '@/components/Navbar';
|
||||
import Footer from '@/components/Footer';
|
||||
import DocsLayout from '@/components/docs/DocsLayout';
|
||||
|
||||
export const metadata = {
|
||||
title: 'Install Paperless-ngx — DashCaddy Docs',
|
||||
description: 'Install and configure Paperless-ngx via DashCaddy. Document management system - scan, organize, and search documents',
|
||||
};
|
||||
|
||||
export default function paperlessNgxDocsPage() {
|
||||
return (
|
||||
<div className="flex min-h-screen flex-col bg-surface-950 text-surface-50">
|
||||
<Navbar />
|
||||
<DocsLayout
|
||||
title="Install Paperless-ngx"
|
||||
intro="Document management system - scan, organize, and search documents"
|
||||
>
|
||||
<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: Productivity</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">ghcr.io/paperless-ngx/paperless-ngx:latest</code></span>
|
||||
</div>
|
||||
|
||||
<h2>What is Paperless-ngx?</h2>
|
||||
<p>Document management system - scan, organize, and search documents</p>
|
||||
<p>Paperless-ngx 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 Paperless-ngx, 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>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>Paperless-ngx</strong> from the <em>Productivity</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>ghcr.io/paperless-ngx/paperless-ngx: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>paperless.<your-domain></code>.</li>
|
||||
<li>Wait for the container health check (<code>/</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 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" \\
|
||||
-H "Content-Type: application/json" \\
|
||||
-d '{
|
||||
"template": "paperless-ngx",
|
||||
"host": "local",
|
||||
"subdomain": "paperless",
|
||||
"port": "{{PORT}}",
|
||||
"environment": {
|
||||
"PAPERLESS_URL": "",
|
||||
"USERMAP_UID": "",
|
||||
"USERMAP_GID": "",
|
||||
"PAPERLESS_TIME_ZONE": "",
|
||||
"PAPERLESS_OCR_LANGUAGE": "",
|
||||
"PAPERLESS_SECRET_KEY": ""
|
||||
},
|
||||
"labels": { "managed-by": "dashcaddy" }
|
||||
}'</code></pre>
|
||||
<p>Response returns a deployment ID. Poll <code>GET /api/v1/apps/{id}/status</code> until <code>state === "running"</code>.</p>
|
||||
|
||||
<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 Paperless-ngx on my home host and expose it at <code>paperless.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>Post-install: first-run checklist</h2>
|
||||
<ol>
|
||||
<li>Create admin account via: docker exec -it <container> python3 manage.py createsuperuser</li>
|
||||
<li>Drop documents into the consume folder for automatic import</li>
|
||||
<li>Configure tags and correspondents for organization</li>
|
||||
</ol>
|
||||
|
||||
|
||||
|
||||
<h2>Volumes and persistent data</h2>
|
||||
<p>DashCaddy creates these volume mounts:</p>
|
||||
<ul>
|
||||
<li><code>/opt/paperless/data:/usr/src/paperless/data</code></li>
|
||||
<li><code>/opt/paperless/media:/usr/src/paperless/media</code></li>
|
||||
<li><code>/opt/paperless/consume:/usr/src/paperless/consume</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>Environment variables</h2>
|
||||
<ul><li><code>PAPERLESS_URL</code></li>
|
||||
<li><code>USERMAP_UID</code></li>
|
||||
<li><code>USERMAP_GID</code></li>
|
||||
<li><code>PAPERLESS_TIME_ZONE</code></li>
|
||||
<li><code>PAPERLESS_OCR_LANGUAGE</code></li>
|
||||
<li><code>PAPERLESS_SECRET_KEY</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>Updating</h2>
|
||||
<p>DashCaddy's built-in Watchtower integration will pull <code>ghcr.io/paperless-ngx/paperless-ngx: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 → Paperless-ngx → Update</strong>.</p>
|
||||
|
||||
<h2>Backups</h2>
|
||||
<p>The config volume for Paperless-ngx 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 Paperless-ngx:</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>Paperless-ngx is in the <strong>Productivity</strong> category. Common pairings:</p>
|
||||
<ul>
|
||||
<li><a href="/docs/catalog/nextcloud" className="text-brand-400 underline">Nextcloud</a></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>paperless-ngx</code>. If anything here looks wrong, edit the file and the change will appear in the next docs rebuild.
|
||||
</p>
|
||||
|
||||
</DocsLayout>
|
||||
<Footer />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
Reference in New Issue
Block a user