diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml new file mode 100644 index 0000000..d55c3b6 --- /dev/null +++ b/.gitea/workflows/deploy.yml @@ -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 }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2eed864 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +kubeconfig +*.secret diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml new file mode 100644 index 0000000..62446b6 --- /dev/null +++ b/.gitlab-ci.yml @@ -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 diff --git a/README.md b/README.md index 0fa6cbf..5aa7ced 100644 --- a/README.md +++ b/README.md @@ -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 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. diff --git a/app.yaml b/app.yaml new file mode 100644 index 0000000..f00ec19 --- /dev/null +++ b/app.yaml @@ -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} diff --git a/ci-deployer.yaml b/ci-deployer.yaml new file mode 100644 index 0000000..7f01171 --- /dev/null +++ b/ci-deployer.yaml @@ -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 diff --git a/create-ci-kubeconfig.sh b/create-ci-kubeconfig.sh new file mode 100755 index 0000000..12276f6 --- /dev/null +++ b/create-ci-kubeconfig.sh @@ -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' diff --git a/deploy.sh b/deploy.sh new file mode 100755 index 0000000..efdee5d --- /dev/null +++ b/deploy.sh @@ -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; } diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..cf4a755 --- /dev/null +++ b/install.sh @@ -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 diff --git a/storage.yaml b/storage.yaml new file mode 100644 index 0000000..401b6ed --- /dev/null +++ b/storage.yaml @@ -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 diff --git a/test.sh b/test.sh new file mode 100755 index 0000000..714025e --- /dev/null +++ b/test.sh @@ -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.'