dashcaddy.net/src/app/docs/catalog/paperless-ngx/page.tsx

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.&lt;your-domain&gt;</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 '&#123;
    "template": "paperless-ngx",
    "host": "local",
    "subdomain": "paperless",
    "port": "&#123;&#123;PORT&#125;&#125;",
    "environment": &#123;
      "PAPERLESS_URL": "",
      "USERMAP_UID": "",
      "USERMAP_GID": "",
      "PAPERLESS_TIME_ZONE": "",
      "PAPERLESS_OCR_LANGUAGE": "",
      "PAPERLESS_SECRET_KEY": ""
    &#125;,
    "labels": &#123; "managed-by": "dashcaddy" &#125;
  &#125;'</code></pre>
        <p>Response returns a deployment ID. Poll <code>GET /api/v1/apps/&#123;id&#125;/status</code> until <code>state === &quot;running&quot;</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 &lt;container&gt; 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>
  );
}