Paperless-ngx on the homelab
One Paperless-ngx instance, SQLite, and Valkey in the paperless-ngx namespace. Documents, database, index, and inbox are on one CephFS PVC. The app is served at https://paper.brunner.ninja through Traefik. Back up the PVC and the paperless-secret-key Secret together.
Install
Run ./install.sh from any directory. It creates the namespace and a random, persistent application secret on first install, checks the manifests with a server dry run, applies them, then waits for both deployments. Open the URL and create the first administrator account in the web UI. Drop scanned files in the web UI or into /usr/src/paperless/consume on the PVC.
Change settings in app.yaml, then run ./test.sh and ./install.sh. The Paperless image is pinned there. The CephFS inbox uses polling because network filesystems may not deliver file notifications.
CI/CD
./test.sh checks syntax and the deployment manifest. ./deploy.sh updates the existing workloads, services, and ingress using app.yaml. The GitLab and Gitea workflows call these same scripts. Bootstrap once with ./create-ci-kubeconfig.sh, then save its single output line as the protected CI variable / Gitea Actions secret KUBE_CONFIG_BASE64. Do not commit it. The deployer has named-object read and patch permissions and cannot read Secrets. Run ./install.sh manually for first installation or changes to storage.yaml.
The Git remote is gitea@brunner.ninja:feedc0de/paperless-ngx-deployment.git. No credentials or generated kubeconfig are committed. To publish changes: git add . && git commit -m 'Deploy Paperless-ngx' && git push origin main.
Authentik login
Paperless supports Authentik through OpenID Connect. In Authentik, create an OAuth2/OpenID Connect application/provider with a strict authorization redirect URI of https://paper.brunner.ninja/accounts/oidc/authentik/login/callback/. Save its client ID and secret outside Git. To enable it, add PAPERLESS_APPS=allauth.socialaccount.providers.openid_connect to the Paperless container environment in app.yaml, and set PAPERLESS_SOCIALACCOUNT_PROVIDERS from a Kubernetes Secret containing the JSON provider configuration described in Authentik's Paperless guide. Keep local login enabled until the Authentik flow has been tested. Existing Paperless users can link their Authentik account from My Profile.
Recovery
The PVC has a Retain storage class. Do not delete it on uninstall. Restore the PVC and the application Secret together. SQLite requires a consistent backup; stop the Paperless deployment or use its document exporter before copying the database.