Skip to content

jackson2w/claude-code-skills / paperless-ngx-bare-metal

paperless-ngx-bare-metal

Verified

This skill should be used when installing, upgrading, or troubleshooting a Paperless-ngx deployment via its bare-metal (non-Docker) release tarball rather than Docker Compose — especially inside a Proxmox LXC. Trigger phrases include "paperless-ngx bare metal", "paperless-ngx without docker", "pip install requirements.txt paperless", "granian paperless", "PAPERLESS_BIND_ADDR", "mysqlclient pkg-config error", "liblept", "paperless-ngx tarball structure", "paperless systemd service", "paperless-webserver.service".

FileKindSize
SKILL.mdskill md8.3 KB
---
name: paperless-ngx-bare-metal
description: This skill should be used when installing, upgrading, or troubleshooting a Paperless-ngx deployment via its bare-metal (non-Docker) release tarball rather than Docker Compose — especially inside a Proxmox LXC. Trigger phrases include "paperless-ngx bare metal", "paperless-ngx without docker", "pip install requirements.txt paperless", "granian paperless", "PAPERLESS_BIND_ADDR", "mysqlclient pkg-config error", "liblept", "paperless-ngx tarball structure", "paperless systemd service", "paperless-webserver.service".
---

# Paperless-ngx bare-metal (non-Docker) install

Covers the gap between Paperless-ngx's official bare-metal docs and what actually happens on a
fresh Debian 13 install — first hit 2026-07-18 building a home document-management LXC
(`paperless`, VMID 144, in the `homelab` repo) with no Docker (Gotenberg is Docker-only and has
no bare-metal alternative at all, but that only matters if Office-document conversion is
needed — pure PDF/scan use, the common "paperless" use case, doesn't need it).

## The release tarball's actual layout — don't assume a versioned top-level dir

`paperless-ngx-v<version>.tar.xz` extracts to a top-level directory literally named
`paperless-ngx/` — **not** version-named. `requirements.txt` sits at that root; `manage.py` is
under `src/` inside it (i.e. `paperless-ngx/src/manage.py`). Confirmed by inspecting the actual
tarball contents (`tar -tJf`), not assumed from docs, which don't spell this out.

If you want side-by-side versions (so a future upgrade doesn't clobber a running install),
extract with `--strip-components=1` into a version-named directory of your own choosing, then
symlink a stable path (e.g. `/opt/paperless/src`) to it:

```bash
mkdir -p /opt/paperless-ngx-2.20.15
tar -xJf paperless-ngx-v2.20.15.tar.xz -C /opt/paperless-ngx-2.20.15 --strip-components=1
ln -sfn /opt/paperless-ngx-2.20.15 /opt/paperless/src
```

With Ansible's `unarchive` module, `extra_opts: ["--strip-components=1"]` does the same thing —
`dest` must already exist as a directory first (unarchive doesn't create it).

## Missing system package: `mysqlclient` needs its dev headers even when using SQLite

The bare-metal docs' package list is incomplete. `requirements.txt` is a single lockfile that
unconditionally includes `mysqlclient` regardless of which `PAPERLESS_DBENGINE` you actually
use — so `pip install -r requirements.txt` fails during `mysqlclient`'s build step with:

```
Trying pkg-config --exists mysqlclient / mariadb / libmariadb / perconaserverclient
...
Exception: Can not find valid pkg-config name.
```

Fix: install `default-libmysqlclient-dev` (the Debian metapackage) even for a pure-SQLite
deployment. This is easy to miss since nothing about a SQLite-only setup suggests you'd need
MySQL client headers.

## Debian 13 package-name drift from older guides

Some bare-metal walkthroughs (and even parts of the current docs) reference package names that
don't exist on Debian 13 (`trixie`). Confirmed via `apt-cache search` rather than assumed:

- Leptonica dev/runtime library is `libleptonica6`, **not** `liblept5`.

If `apt install <package>` 404s on a name from a guide, search first (`apt-cache search
<library-name>`) rather than assuming the package was removed — it's very likely just renamed.

## The webserver is Granian (ASGI), not Gunicorn

Current Paperless-ngx (2.x) uses **Granian** as its production ASGI server
(`granian --interface asginl --ws --loop uvloop paperless.asgi:application`), pulled in via
`requirements.txt` alongside `uvloop`. Older guides/assumptions referencing Gunicorn are stale.
Get the real, current systemd unit templates from the upstream repo before writing your own —
they live at `scripts/paperless-webserver.service`, `paperless-consumer.service`,
`paperless-scheduler.service`, `paperless-task-queue.service` (not under a `systemd/`
subdirectory, despite what the name might suggest) — `gh api
repos/paperless-ngx/paperless-ngx/contents/scripts` to list them, fetch with `--jq '.content' |
base64 -d`.

**`PAPERLESS_BIND_ADDR` defaults to `::`** (all interfaces, IPv4+IPv6) — confirmed directly
against the upstream unit template's `GRANIAN_HOST` handling, not assumed. Same "binds
everywhere by default" gotcha as Next.js/Jellyfin elsewhere in this homelab — set it explicitly
to `127.0.0.1` if the plan is to front it with Tailscale Serve (or any reverse proxy) and verify
with a negative check (confirm the plain LAN IP:port is actually refused), not just that the
proxied hostname works.

The systemd templates' `Requires=redis.service` may not match your distro's actual unit name —
Debian's `redis-server` package installs as `redis-server.service`; don't assume a `redis.service`
alias exists, use the real name.

## `PAPERLESS_URL` is the one env var to set, not three

Setting `PAPERLESS_URL=https://your-hostname` configures `ALLOWED_HOSTS`, `CORS_ALLOWED_HOSTS`,
and `CSRF_TRUSTED_ORIGINS` together — simpler and less error-prone than setting Django's usual
three separate variables by hand, and the CSRF piece specifically matters (Django 4+ requires
`CSRF_TRUSTED_ORIGINS` for POST through any reverse proxy, including Tailscale Serve).

## `sudo` may not exist on a minimal LXC template

If your automation tries to run `manage.py migrate`/`createsuperuser`/`collectstatic` as the
dedicated `paperless` service user via Ansible's `become`/`become_user`, it can fail with a
literal `/bin/sh: 1: sudo: not found` if the base template doesn't ship `sudo` — common for
minimal Debian LXC templates in this kind of homelab fleet. Rather than adding `sudo` just for
this, run these one-off setup commands as root (same as they'd run over a root SSH connection
regardless) and let a recursive ownership-fix step afterward (`chown -R paperless:paperless
...`) correct any root-owned files those commands created — this matches the existing
root-then-chown pattern already used for other native-install services in this fleet (n8n,
Homepage) rather than introducing a new dependency.

## Verifying OCR for real, not just "upload succeeded"

A `200`/task-`SUCCESS` response only proves the document was accepted and processed *some* way
— it doesn't prove OCR actually ran. To verify OCR text extraction genuinely works:

1. Generate an **image-only** test PDF (no embedded text layer) so the pipeline can't cheat by
   reusing an existing text layer instead of actually running Tesseract:
   ```bash
   convert -size 1000x300 xc:white -gravity center -pointsize 48 -fill black \
     -annotate 0 "SOME_UNIQUE_TEST_STRING" /tmp/test.png
   convert /tmp/test.png /tmp/test.pdf
   ```
2. Upload via the API (`POST /api/documents/post_document/`, `Authorization: Token <token>`,
   multipart `document=@test.pdf`) — returns a task UUID.
3. Poll `GET /api/tasks/?task_id=<uuid>` until `status` is `SUCCESS` (or `FAILURE`).
4. Confirm via `GET /api/documents/?query=SOME_UNIQUE_TEST_STRING` that the document is found
   **and** its `content` field contains the exact string — this is the actual proof OCR read
   the image correctly, not just that a file landed on disk.
5. `GET /api/documents/<id>/thumb/` should return `200` with real image bytes — confirms
   thumbnail generation, a separate pipeline step from OCR.

Delete the test document afterward (`DELETE /api/documents/<id>/`) — don't leave synthetic test
data in a personal document archive.

## A shell-quoting trap when generating credentials over nested SSH

If a generated password (e.g. `openssl rand -base64 N`) needs to pass through more than one
layer of shell quoting (e.g. a local script building a remote command that itself runs a
further-nested SSH command), characters like `+`, `/`, `=` can silently get mangled without any
error at creation time — `createsuperuser --noinput` reports success, but the account then
can't log in, and the failure only surfaces later at the login attempt, disconnected from the
actual cause. **Use `openssl rand -hex N` instead** (alphanumeric-only output) for any credential
that has to transit multiple shell layers, sidestepping the whole class of quoting bugs rather
than trying to escape correctly through every layer. If a password already went in wrong, fix it
with `manage.py changepassword <username>` reading the new value from its own interactive
prompt (via a here-string/heredoc on stdin) rather than as a command-line argument.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall