Deploy Paperless-ngx to homelab
This commit is contained in:
1 parent
dddee23b0b
commit
e265ed3f9d
11 files changed
+311
-1
No files matched your search
@@ -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 }}
|
||||
@@ -0,0 +1,2 @@
|
||||
kubeconfig
|
||||
*.secret
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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}
|
||||
@@ -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
|
||||
Executable
+27
@@ -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'
|
||||
@@ -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
@@ -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
|
||||
@@ -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
|
||||
@@ -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.'
|
||||
Reference in new issue
Block a user