forust
033a69bc1e
ci / Compose (pull_request) Successful in 15s
ci / Workflows (pull_request) Successful in 9s
ci / Shell (pull_request) Successful in 19s
ci / Formatting (pull_request) Successful in 24s
ci / Python and tests (pull_request) Successful in 11s
ci / YAML (pull_request) Successful in 10s
ci / Dockerfiles (pull_request) Successful in 6s
ci / Kubernetes (pull_request) Successful in 7s
ci / image-plan (pull_request) Skipped
ci / Image (${{ matrix.name }}) (pull_request) Skipped
ci / build (pull_request) Skipped
80 lines
3.1 KiB
Markdown
80 lines
3.1 KiB
Markdown
# Paperless-ngx
|
|
|
|
Paperless-ngx runs in the `paperless` namespace. It uses the shared PostgreSQL
|
|
service in the `database` namespace and Valkey for its task queue. The document
|
|
library, exports, and consume folder are stored on the `local-path-retain`
|
|
volume. The PVC size is fixed at 50 GiB because this storage class does not
|
|
support volume expansion.
|
|
|
|
The local route is `https://papers.workstation.internal`; the public route is
|
|
`https://papers.forust.xyz`. Both use TLS. Paperless keeps its own login and
|
|
password authentication. OCR is configured for Russian and English documents.
|
|
Keep `papers.forust.xyz` in the existing Cloudflare DDNS `DOMAINS` setting so
|
|
the public record follows the workstation address.
|
|
|
|
## Compose alternative
|
|
|
|
`compose.yaml` is an alternative to the active Kubernetes deployment. Do not
|
|
run both at the same time: they use the same Paperless database and route
|
|
names, but have separate document volumes.
|
|
|
|
The Compose variant uses the shared Compose PostgreSQL service on the
|
|
`homelab-database` Docker network. It does not start a PostgreSQL container.
|
|
The shared Compose database must be running and must have the `paperless`
|
|
database and role. Set `PAPERLESS_DBPASS` to the same password as
|
|
`PAPERLESS_DB_PASSWORD` in the shared PostgreSQL configuration.
|
|
|
|
To prepare and start the Compose variant:
|
|
|
|
```sh
|
|
cp paperless/.env.example paperless/.env
|
|
cd paperless
|
|
docker compose -f compose.yaml config --quiet
|
|
docker compose -f compose.yaml up -d
|
|
```
|
|
|
|
Create unique values for `PAPERLESS_SECRET_KEY` and
|
|
`PAPERLESS_ADMIN_PASSWORD` in `.env`. This directory has no Compose `active`
|
|
marker, so the repository deploy workflow does not start this alternative.
|
|
Stop the Kubernetes Paperless deployment before switching to Compose. Back up
|
|
and migrate the media files as well as the database; the Compose named volumes
|
|
are separate from the Kubernetes PVC.
|
|
|
|
## Prepare the secret
|
|
|
|
Create `k8s/secrets.yaml` on the workstation from
|
|
`k8s/secrets.yaml.example`. Set a unique random `PAPERLESS_SECRET_KEY`, a long
|
|
`PAPERLESS_ADMIN_PASSWORD`, and `PAPERLESS_DB_PASSWORD`.
|
|
|
|
Add the same `PAPERLESS_DB_PASSWORD` value to the local
|
|
`postgres/k8s/secrets.yaml` file. Keep both secret files out of Git. The
|
|
database bootstrap Job creates the `paperless` role and database from the
|
|
shared PostgreSQL secret. The job runs in the `database` namespace and needs
|
|
that namespace's existing `postgres-shared-secrets` Secret.
|
|
|
|
For example, generate a key with:
|
|
|
|
```sh
|
|
python3 -c 'import secrets; print(secrets.token_urlsafe(64))'
|
|
```
|
|
|
|
Then apply the secret before enabling the service:
|
|
|
|
```sh
|
|
kubectl apply -f paperless/k8s/namespace.yaml
|
|
kubectl apply -f postgres/k8s/secrets.yaml
|
|
kubectl apply -f paperless/k8s/secrets.yaml
|
|
```
|
|
|
|
The normal deploy workflow applies the remaining manifests when
|
|
`paperless/k8s/active` is present. Verify the rollout and ingress after deploy:
|
|
|
|
```sh
|
|
kubectl -n paperless rollout status deployment/paperless
|
|
kubectl -n paperless get pods,pvc,services
|
|
```
|
|
|
|
Back up the `paperless-data` PVC and the shared PostgreSQL database. The PVC
|
|
contains the originals, archived PDFs, and export/consume folders. Valkey has
|
|
no persistent volume; queued tasks are recreated after a restart.
|