Deploy Paperless-ngx to homelab
Test and deploy / test (push) Failing after 32s
Test and deploy / deploy (push) Skipped

This commit is contained in:
feedc0de committed 2026-10-04 17:07:32 +02:00
1 parent dddee23b0b
commit e265ed3f9d
11 files changed
+311 -1

No files matched your search

+28
View File
@@ -0,0 +1,28 @@
name: Test and deploy
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
container: alpine/k8s:1.33.0
steps:
- uses: actions/checkout@v4
- run: apk add --no-cache bash jq && ./test.sh
deploy:
if: github.event_name == 'push'
needs: test
runs-on: ubuntu-latest
container: alpine/k8s:1.33.0
steps:
- uses: actions/checkout@v4
- run: apk add --no-cache bash jq
- run: |
umask 077
echo "$KUBE_CONFIG_BASE64" | base64 -d > kubeconfig
export KUBECONFIG="$PWD/kubeconfig"
./deploy.sh
rm -f kubeconfig
env:
KUBE_CONFIG_BASE64: ${{ secrets.KUBE_CONFIG_BASE64 }}
+2
View File
@@ -0,0 +1,2 @@
kubeconfig
*.secret
+22
View File
@@ -0,0 +1,22 @@
stages: [test, deploy]
test:
stage: test
image: alpine/k8s:1.33.0
script:
- apk add --no-cache bash jq
- ./test.sh
deploy:
stage: deploy
image: alpine/k8s:1.33.0
rules:
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
script:
- apk add --no-cache bash jq
- umask 077
- echo "$KUBE_CONFIG_BASE64" | base64 -d > kubeconfig
- export KUBECONFIG="$CI_PROJECT_DIR/kubeconfig"
- ./deploy.sh
after_script:
- rm -f kubeconfig
+22 -1
View File
@@ -1,2 +1,23 @@
# paperless-ngx-deployment
# 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](https://integrations.goauthentik.io/documentation/paperless-ngx/). 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.
+120
View File
@@ -0,0 +1,120 @@
apiVersion: apps/v1
kind: Deployment
metadata:
name: valkey
namespace: paperless-ngx
spec:
replicas: 1
strategy:
type: Recreate
selector:
matchLabels: {app: valkey}
template:
metadata:
labels: {app: valkey}
spec:
automountServiceAccountToken: false
containers:
- name: valkey
image: valkey/valkey:9.0.6
args: ["--save", "", "--appendonly", "no"]
ports: [{name: redis, containerPort: 6379}]
readinessProbe:
exec: {command: [valkey-cli, ping]}
periodSeconds: 5
livenessProbe:
exec: {command: [valkey-cli, ping]}
periodSeconds: 20
resources:
requests: {cpu: 25m, memory: 64Mi}
limits: {memory: 256Mi}
---
apiVersion: v1
kind: Service
metadata:
name: valkey
namespace: paperless-ngx
spec:
selector: {app: valkey}
ports: [{name: redis, port: 6379, targetPort: redis}]
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: paperless
namespace: paperless-ngx
spec:
replicas: 1
strategy:
type: Recreate
selector:
matchLabels: {app: paperless}
template:
metadata:
labels: {app: paperless}
spec:
automountServiceAccountToken: false
enableServiceLinks: false
containers:
- name: paperless
image: ghcr.io/paperless-ngx/paperless-ngx:3.2.1
ports: [{name: http, containerPort: 8000}]
env:
- {name: PAPERLESS_URL, value: "https://paper.brunner.ninja"}
- {name: PAPERLESS_REDIS, value: "redis://valkey:6379"}
- {name: PAPERLESS_TIME_ZONE, value: "Europe/Vienna"}
- {name: PAPERLESS_OCR_LANGUAGE, value: "deu+eng"}
- {name: PAPERLESS_CONSUMER_POLLING_INTERVAL, value: "30"}
- name: PAPERLESS_SECRET_KEY
valueFrom:
secretKeyRef: {name: paperless-secret-key, key: secret-key}
volumeMounts:
- {name: data, mountPath: /usr/src/paperless/data, subPath: data}
- {name: data, mountPath: /usr/src/paperless/media, subPath: media}
- {name: data, mountPath: /usr/src/paperless/consume, subPath: consume}
- {name: data, mountPath: /usr/src/paperless/export, subPath: export}
startupProbe:
httpGet: {path: /, port: http}
periodSeconds: 10
failureThreshold: 60
readinessProbe:
httpGet: {path: /, port: http}
periodSeconds: 10
livenessProbe:
httpGet: {path: /, port: http}
periodSeconds: 30
resources:
requests: {cpu: 100m, memory: 512Mi}
limits: {memory: 2Gi}
volumes:
- name: data
persistentVolumeClaim: {claimName: paperless-data}
---
apiVersion: v1
kind: Service
metadata:
name: paperless
namespace: paperless-ngx
spec:
selector: {app: paperless}
ports: [{name: http, port: 8000, targetPort: http}]
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: paperless
namespace: paperless-ngx
annotations:
traefik.ingress.kubernetes.io/router.entrypoints: websecure
spec:
ingressClassName: traefik
rules:
- host: paper.brunner.ninja
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: paperless
port: {name: http}
+47
View File
@@ -0,0 +1,47 @@
apiVersion: v1
kind: ServiceAccount
metadata:
name: paperless-deployer
namespace: paperless-ngx
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: paperless-deployer
namespace: paperless-ngx
rules:
- apiGroups: [apps]
resources: [deployments]
resourceNames: [paperless, valkey]
verbs: [get, patch, watch]
- apiGroups: [""]
resources: [services]
resourceNames: [paperless, valkey]
verbs: [get, patch]
- apiGroups: [networking.k8s.io]
resources: [ingresses]
resourceNames: [paperless]
verbs: [get, patch]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: paperless-deployer
namespace: paperless-ngx
subjects:
- kind: ServiceAccount
name: paperless-deployer
namespace: paperless-ngx
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: paperless-deployer
---
apiVersion: v1
kind: Secret
metadata:
name: paperless-deployer-token
namespace: paperless-ngx
annotations:
kubernetes.io/service-account.name: paperless-deployer
type: kubernetes.io/service-account-token
+27
View File
@@ -0,0 +1,27 @@
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "${BASH_SOURCE[0]}")"
[[ $(kubectl config current-context) == kubernetes-admin@kubernetes ]] || { echo 'Wrong Kubernetes context' >&2; exit 1; }
manifest=$(kubectl create --dry-run=client --validate=false -f ci-deployer.yaml -o json)
namespace=$(jq -r 'select(.kind == "ServiceAccount") | .metadata.namespace' <<<"${manifest}")
account=$(jq -r 'select(.kind == "ServiceAccount") | .metadata.name' <<<"${manifest}")
secret=$(jq -r 'select(.kind == "Secret") | .metadata.name' <<<"${manifest}")
kubectl apply -f ci-deployer.yaml >&2
for attempt in {1..30}; do
token=$(kubectl -n "${namespace}" get secret "${secret}" -o jsonpath='{.data.token}' 2>/dev/null || true)
[[ -n ${token} ]] && break
sleep 1
done
[[ -n ${token:-} ]] || { echo 'Service account token was not issued' >&2; exit 1; }
workdir=$(mktemp -d)
trap 'rm -rf "${workdir}"' EXIT
server=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
kubectl -n "${namespace}" get secret "${secret}" -o jsonpath='{.data.ca\.crt}' | base64 -d > "${workdir}/ca.crt"
export KUBECONFIG="${workdir}/config"
kubectl config set-cluster homelab --server="${server}" --certificate-authority="${workdir}/ca.crt" --embed-certs=true >/dev/null
kubectl config set-credentials "${account}" --token="$(printf '%s' "${token}" | base64 -d)" >/dev/null
kubectl config set-context homelab --cluster=homelab --user="${account}" --namespace="${namespace}" >/dev/null
kubectl config use-context homelab >/dev/null
echo 'Save the following line as KUBE_CONFIG_BASE64; do not commit it:' >&2
base64 -w0 "${KUBECONFIG}"
printf '\n'
Executable
+7
View File
@@ -0,0 +1,7 @@
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "${BASH_SOURCE[0]}")"
./test.sh
kubectl apply -f app.yaml
kubectl -n paperless-ngx rollout status deployment/valkey --timeout=5m || { kubectl -n paperless-ngx describe deployment valkey; exit 1; }
kubectl -n paperless-ngx rollout status deployment/paperless --timeout=15m || { kubectl -n paperless-ngx describe deployment paperless; exit 1; }
Executable
+14
View File
@@ -0,0 +1,14 @@
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "${BASH_SOURCE[0]}")"
[[ $(kubectl config current-context) == kubernetes-admin@kubernetes ]] || { echo 'Wrong Kubernetes context' >&2; exit 1; }
kubectl create namespace paperless-ngx --dry-run=client -o yaml | kubectl apply -f -
if ! kubectl -n paperless-ngx get secret paperless-secret-key >/dev/null 2>&1; then
key=$(openssl rand -base64 64)
kubectl -n paperless-ngx create secret generic paperless-secret-key --from-literal="secret-key=${key}"
fi
./test.sh
kubectl apply --dry-run=server -f storage.yaml -f app.yaml
kubectl apply -f storage.yaml -f app.yaml
kubectl -n paperless-ngx rollout status deployment/valkey --timeout=5m
kubectl -n paperless-ngx rollout status deployment/paperless --timeout=15m
+11
View File
@@ -0,0 +1,11 @@
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: paperless-data
namespace: paperless-ngx
spec:
accessModes: [ReadWriteMany]
storageClassName: rook-cephfs-ec
resources:
requests:
storage: 20Gi
Executable
+11
View File
@@ -0,0 +1,11 @@
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "${BASH_SOURCE[0]}")"
bash -n install.sh deploy.sh create-ci-kubeconfig.sh test.sh
kubectl create --dry-run=client --validate=false -f storage.yaml -f app.yaml -f ci-deployer.yaml -o json >/dev/null
images=$(kubectl create --dry-run=client --validate=false -f app.yaml -o json | jq -r 'select(.kind == "Deployment") | .spec.template.spec.containers[].image')
[[ -n $images ]]
while IFS= read -r image; do
[[ $image == *:* && $image != *:latest ]]
done <<<"${images}"
echo 'Manifest valid; deployment images are pinned.'