Installation steps — Euro-Office Docs and Nextcloud

Date: 2026-10-28 Working directory: content/opentofu Target cluster: the Talos/Kubernetes cluster described in access-sites.md (3 control-plane nodes, Kubernetes v1.31.1, Traefik ingress, local-path storage).

This document records how Euro-Office Docs and Nextcloud were installed with Argo CD, including every deviation from install-euro-office.md that was needed for this cluster.

Result: installed and verified. Both Argo CD Applications are Synced/Healthy, and the Nextcloud connector reports Document server http://euro-office.kubernetes.local/ version 9.3.1.37 is successfully connected. See section 12.


1. Environment and pre-flight checks

ItemValue
Nodestalos-node-1 / talos-node-2 / talos-node-3
Node capacity2 vCPU, 4 GiB RAM, 20 GB system disk each
Allocatable per node~1950m CPU, ~3.2 GiB RAM, ~17.8 GB ephemeral storage
Ingress controllerTraefik (IngressClass traefik, NodePort 30080/30443)
Default StorageClasslocal-path (rancher.io/local-path, RWO)
Argo CDargocd namespace, app-of-apps root Application root
GitOps repositoryForgejo gitea_admin/gitops, path apps

Checks performed:

kubectl get nodes -o custom-columns=NAME:.metadata.name,CPU:.status.allocatable.cpu,MEM:.status.allocatable.memory
kubectl get sc
kubectl get ingressclass
kubectl get applications -n argocd

The cluster had roughly 2.2 GiB of free memory per node. Euro-Office is a memory-hungry workload, so all resource requests/limits were reduced (see section 5) and the Euro-Office pods were pinned to one node.

1.1 Upstream chart availability

The chart URL used by the guide, https://euro-office.github.io/Kubernetes-Docs/, returns 404. The documented Helm repository https://download.euro-office.com/charts/stable is now a parked domain: HTTP returns an HTML landing page and HTTPS fails with tlsv1 unrecognized name.

The chart source is still published in the official repository:

The chart was therefore vendored into the GitOps repository instead of being fetched from a Helm repository. The Nextcloud chart (nextcloud/nextcloud 8.3.0, app 32.0.0) was vendored the same way.

The Euro-Office chart defaults to image tag 9.3.1-1, which is not published on GHCR. The published tag is v9.3.1, so that value is overridden.


2. Namespaces

kubectl create namespace euro-office
kubectl create namespace nextcloud

kubectl create namespace nfs-server
kubectl label namespace nfs-server \
  pod-security.kubernetes.io/enforce=privileged --overwrite

nfs-server needs the privileged Pod Security label because the NFS provisioner adds the DAC_READ_SEARCH and SYS_RESOURCE capabilities, which are not allowed by the default baseline profile.


3. ReadWriteMany storage for Euro-Office

The Euro-Office chart hardcodes ReadWriteMany for its three PVCs (ds-files, ds-runtime-config, ds-buffer). local-path only supports ReadWriteOnce, so an NFS provisioner was installed, exactly as the upstream guide recommends.

helm repo add nfs-server-provisioner \
  https://kubernetes-sigs.github.io/nfs-ganesha-server-and-external-provisioner
helm repo update

helm upgrade --install nfs-server \
  nfs-server-provisioner/nfs-server-provisioner \
  --namespace nfs-server \
  --set persistence.enabled=true \
  --set persistence.storageClass=local-path \
  --set persistence.size=8Gi \
  --set storageClass.name=nfs \
  --set storageClass.defaultClass=false \
  --set resources.requests.cpu=50m \
  --set resources.requests.memory=64Mi \
  --set resources.limits.memory=256Mi \
  --wait --timeout 6m

Result:

ppSoetdro/srniafsgste-eCsnletarvsvoselrun-mfnesfcsl-asikemur/bdeearrtn-aep-trneofsvs.i-issoie/ornnvfeesrr---s0nefrsv-e1sr/e-1rpvreorvR-iupsnrinooivnniegsrioneDre-l0eteBouInmdmedi8aGtieRWOlocal-path

The chart’s PVC sizes were reduced to fit the 8 GiB backing volume: ds-files 4 GiB + ds-runtime-config 1 GiB (+ optional ds-buffer 2 GiB).


4. Prerequisite services

The Euro-Office chart expects three external services. Instead of the Bitnami charts used by the upstream README (whose legacy images are being retired), the services were deployed as small plain manifests with the official upstream images. This keeps the image set small and avoids Bitnami catalog changes.

All three run in the euro-office namespace. The manifests and the setup script are stored in ansible2/files/gitops/prereqs/ (they are applied manually; Argo CD does not manage them).

4.1 PostgreSQL

kubectl -n euro-office get deploy,svc,pvc
kubectl -n euro-office exec deploy/postgres -- psql -U postgres -l

4.2 Redis

4.3 RabbitMQ

The readiness probe initially used the default 1-second timeout and always failed with rabbitmq-diagnostics -q ping (the command takes longer than one second even on a healthy node). It was corrected to:

readinessProbe:
  exec:
    command: ["rabbitmq-diagnostics", "-q", "ping"]
  initialDelaySeconds: 20
  periodSeconds: 10
  timeoutSeconds: 15
  failureThreshold: 6

4.4 Secrets

Secrets are created out of band; no passwords are stored in this document or in the GitOps repository:

SecretNamespaceKeys
postgres-credentialseuro-officePOSTGRES_PASSWORD, EUROOFFICE_DB_PASSWORD, NEXTCLOUD_DB_PASSWORD
eurooffice-dbeuro-officepassword
rediseuro-officeredis-password
rabbitmqeuro-officerabbitmq-password
euro-office-jwteuro-officeJWT_SECRET
nextcloud-dbnextcloudusername, password
nextcloud-adminnextcloudusername, password

They were generated with openssl rand -hex … and applied with kubectl create secret generic --dry-run=client -o yaml | kubectl apply -f -. The temporary credentials file used during the run lived only on the management container and was deleted afterwards.


5. Helm values adaptations

Both charts are vendored under ansible2/files/gitops/charts/:

c├│└h──a──rte└n└su─e─/r─x─ot-vcvoalaflolfuuuiedecs/se---kkd88ossc..syy/aammll##uuppssttrreeaammKnuebxetrcnleotueds-8D.o3c.s06.0.0

5.1 Euro-Office Docs

charts/euro-office-docs/values-k8s.yaml differs from the upstream defaults as follows:

SettingValueReason
images.tagv9.3.19.3.1-1 is not published on GHCR
nodeSelectorkubernetes.io/hostname: talos-node-1pull the 1.4 GB image once; keep memory-heavy pods together
ingress.enabledtrueexpose the service
ingress.ingressClassNametraefikcluster uses Traefik, not NGINX
ingress.hosteuro-office.kubernetes.localhomelab DNS name
ingress.ssl.enabledfalseno cert-manager in this cluster
jwt.existingSecreteuro-office-jwtJWT secret is not committed
connections.dbExistingSecreteurooffice-dbDB password is not committed
connections.dbNameeuroofficededicated database
connections.redisHostredis-mastermatches the Redis Service
connections.amqpHostrabbitmqmatches the RabbitMQ Service
persistence.storageClassnfschart requires ReadWriteMany
persistence.size4Gifit the 8 GiB NFS backing volume
persistence.runtimeConfig.size1Gisame
persistence.customResources.enabledfalsenot needed; saves a PVC and job
docservice.replicas1small cluster
converter.replicas1small cluster
docservice.resourcesrequests 250m/512Mi, limits 2 CPU/2Gifit node
converter.resourcesrequests 200m/256Mi, limits 1 CPU/1Gifit node
proxy.resourcesrequests 100m/128Mi, limits 500m/512Mifit node
metrics.enabledfalsenot required
adminpanel.enabledfalsenot required
example.enabledtruedeploy the chart’s example/test page at /example/
tests.enabledfalseno Helm test pods
upgrade.job.enabledfalseArgo CD also runs pre-upgrade hooks on install
rollback.job.enabledfalsesame
sqlScripts.branchNamemainschema lives on the Euro-Office fork
requestFilteringAgent.allowPrivateIPAddresstruethe document server must download files from Nextcloud’s private ClusterIP

Two templates in the vendored chart were patched as well:

5.2 Nextcloud

charts/nextcloud/values-k8s.yaml uses:

SettingValueReason
ingress.enabledtrueexpose the service
ingress.classNametraefikTraefik
nextcloud.hostnextcloud.kubernetes.localhomelab DNS name
nextcloud.existingSecretnextcloud-adminadmin password is not committed
persistence.storageClasslocal-pathRWO is sufficient for the Nextcloud data volume
persistence.size5Gifit the node disks
internalDatabase.enabledfalseno SQLite
externalDatabasePostgreSQL at postgresql.euro-office.svc.cluster.localreuse the Euro-Office database server
externalDatabase.existingSecretnextcloud-dbDB password is not committed
mariadb.enabledfalseno bundled MariaDB
postgresql.enabledfalseno bundled PostgreSQL
redis.enabledfalseno bundled Redis
collabora.enabledfalseEuro-Office is the document server
resourcesrequests 200m/256Mi, limits 1 CPU/1Gifit node
probeslonger initial delaysfirst start initialises the database

5.3 Example application

example.enabled: true deploys the chart’s example application: a StatefulSet named example, a Service named example on port 3000, and a ConfigMap with DS_URL. The document server’s proxy routes /example/ to example:3000; the main documentserver ConfigMap gets EXAMPLE_HOST_PORT=example:3000.

Values added to values-k8s.yaml:

example:
  enabled: true
  # The example entrypoint defaults JWT_ENABLED to false. The document server
  # requires JWT, so without this the editor config has no token.
  extraEnvVars:
    - name: JWT_ENABLED
      value: "true"
    - name: JWT_HEADER
      value: Authorization
    # Server-to-server URL used by the document server to download the file
    # and post callbacks. The public /example/ prefix is stripped by the
    # documentserver proxy, so use the example Service root here.
    - name: EXAMPLE_URL
      value: http://example:3000
  # Avoid the chart's random `rollme` annotation, which would make Argo CD
  # see a diff on every render and restart the StatefulSet.
  podAnnotations: {}
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: 500m
      memory: 512Mi

JWT_SECRET already comes from the euro-office-jwt secret via envFrom. The example image’s docker-entrypoint.sh defaults JWT_ENABLED to false, so the two extra vars above are required; otherwise the editor config has an empty token and the document server logs jwt must be provided.

The image also defaults EXAMPLE_URL to http://localhost/example/. That is not reachable from the document server pod. Setting it to http://example:3000 (no trailing slash) points at the example Service root; the app appends /download and /track, so a trailing slash would produce //download and return 404. The /example/ prefix is the browser-facing route handled by the documentserver proxy (which strips it before forwarding).

The example image is ghcr.io/euro-office/cluster-example:v9.3.1 (about 117 MB compressed) and is pinned to talos-node-1 by the global nodeSelector. After Argo CD updates the ConfigMap, restart the docservice Deployment so the proxy picks up the new EXAMPLE_HOST_PORT:

kubectl -n euro-office rollout restart deploy/docservice

This is the equivalent of the upstream command:

helm install documentserver onlyoffice/docs --set example.enabled=true

The chart is already managed by Argo CD, so the value is changed in values-k8s.yaml instead of running a second helm install (which would collide with the existing release/resources).


6. Argo CD Applications

Two Application manifests were added at the top level of apps/:

The root Application syncs path: apps, but Argo CD’s directory source does not recurse by default. The manifests were therefore placed directly in apps/, not in apps/office/.

Both Applications use the vendored chart from the in-cluster Forgejo repository:

source:
  repoURL: http://forgejo-http.forgejo.svc.cluster.local:3000/gitea_admin/gitops.git
  targetRevision: HEAD
  path: charts/euro-office-docs        # or charts/nextcloud
  helm:
    releaseName: documentserver        # or nextcloud
    valueFiles:
      - values-k8s.yaml
destination:
  namespace: euro-office               # or nextcloud
syncPolicy:
  automated:
    prune: true
    selfHeal: true
  syncOptions:
    - CreateNamespace=true

The manifests explicitly set metadata.namespace: argocd so the root Application creates them in the Argo CD namespace.

Git commits pushed to the GitOps repository during this installation:

CommitChange
50e817badd both vendored charts and the initial Application manifests
970b9f0move Applications from apps/office/ to apps/ (root does not recurse)
2e4b66apin Euro-Office pods to talos-node-1
0f5755cdisable Euro-Office pre-upgrade/pre-rollback hooks
1046d5cpoint schema downloads at Euro-Office/server main
89a0b8aadd the missing COMPANY_NAME env var to the Euro-Office ConfigMap
b6f0760allow the document server to reach private ClusterIPs
7e946c9add the prerequisite manifests and setup script under prereqs/
3188cccenable the Euro-Office example application (/example/)
57e97deenable JWT in the example so the editor token is accepted
f4e593buse the example Service root for document-server downloads/callbacks

After each push, the root Application was refreshed with:

kubectl -n argocd annotate application root \
  argocd.argoproj.io/refresh=normal --overwrite

7. Problems found and corrections

7.1 The guide’s chart repository no longer exists

7.2 Image tag 9.3.1-1 does not exist

GHCR publishes v9.3.1, not 9.3.1-1. The pod would otherwise stay in ImagePullBackOff. fix: images.tag: v9.3.1.

7.3 Root Application does not recurse

The Applications were first placed in apps/office/, but the root Application only syncs files directly under apps/. fix: move them to apps/euro-office.yaml and apps/nextcloud.yaml.

7.4 pre-upgrade hook runs on a fresh install

Argo CD maps both pre-install and pre-upgrade Helm hooks to PreSync. The pre-upgrade hook tries to disable the docservice service, which does not exist yet, and fails with:

ThCeousledrvneortcroeuslodlvneothobset:didsoacbsleerdvice

fix: set upgrade.job.enabled: false and rollback.job.enabled: false in values-k8s.yaml. On upgrades, run those hooks manually if needed.

7.5 Database schema download returns 404

The chart’s pre-install job downloads schema/postgresql/createdb.sql from ONLYOFFICE/server/master. That path no longer exists. The job logged:

HwToTrPkrdeoqnueestsent,awaitingresponse...404NotFound

…but the eurooffice database stayed empty.

fix (one-time): apply the schema from the Euro-Office fork manually:

curl -fsSL https://raw.githubusercontent.com/Euro-Office/server/main/schema/postgresql/createdb.sql \
  -o /tmp/createdb.sql
{ echo "SET ROLE eurooffice;"; cat /tmp/createdb.sql; } \
  | kubectl -n euro-office exec -i deploy/postgres -- \
      psql -U postgres -d eurooffice -v ON_ERROR_STOP=1

fix (reproducible): the vendored chart templates now point at https://raw.githubusercontent.com/Euro-Office/server/{{ branch }}/… and sqlScripts.branchName: main.

Verify:

kubectl -n euro-office exec deploy/postgres -- \
  psql -U postgres -d eurooffice -c '\dt'

Expected: doc_changes and task_result, both owned by eurooffice.

7.6 Very slow image pulls

The cluster’s uplink delivered roughly 0.3–1 MB/s during the installation. The Euro-Office main image (cluster-docs) is about 1.4 GB and the utilities image (cluster-utils) about 361 MB; the Nextcloud image is about 519 MB.

Mitigations:

This is an environment limitation, not a chart problem.

7.7 RabbitMQ readiness probe timeout

See section 4.3. The default 1-second probe timeout is too short for rabbitmq-diagnostics -q ping.

7.8 Missing COMPANY_NAME makes all containers exit

After the images were finally cached, both Euro-Office Deployments went into CrashLoopBackOff with exit code 2 and only these log lines:

sseedd::ccaann''ttrreeaadd/evtacr/wdwowc/u/mdeonctusmeernvtesre/rlvoegr4-jesx/apmrpoldeu/cwteilocno.mjesand:miNno-dsiuscahblfeidl.ehtomrl:diNroecstuocrhyfileordirectory

The double slash is the clue. The cluster-docs:v9.3.1 entrypoints use $COMPANY_NAME:

WELCOME_PATH="/var/www/$COMPANY_NAME/documentserver-example/welcome"
sed ... /etc/$COMPANY_NAME/documentserver/log4js/production.json

The image provides COMPANY_NAME_LOW=euro-office, and the chart sets APPLICATION_NAME=euro-office, but neither sets COMPANY_NAME. With an empty variable the paths become /var/www//… and /etc//…, sed returns 2, and set -e terminates the entrypoint.

fix: add COMPANY_NAME: {{ .Values.product.name }} to templates/configmaps/documentserver.yaml (commit 89a0b8a), then restart the Deployments so the new environment is injected:

kubectl -n euro-office patch cm documentserver --type merge \
  -p '{"data":{"COMPANY_NAME":"euro-office"}}'
kubectl -n euro-office rollout restart deploy/docservice deploy/converter

Result: docservice 2/2 and converter 1/1 Running.

7.9 Connector cannot download the test document

With the document server up, the Nextcloud connector check still failed:

EErrrroorrcwohninleectdioownn:loEardrionrgotchceurdroecdumienntthfeildeoctuomebnetcsoenrvveirctee:d.

Three separate problems were involved:

  1. Wrong port. The Nextcloud chart’s Service exposes http on port 8080 (targetPort: 80). StorageUrl had been set to http://nextcloud.nextcloud.svc.cluster.local/ (port 80), so the request was refused: curl: (7) Failed to connect ... port 80.
  2. Private-IP filter. requestFilteringAgent.allowPrivateIPAddress defaults to false, so the document server refuses to fetch files from a 10.x ClusterIP.
  3. Untrusted hostname. Nextcloud only accepts localhost and nextcloud.kubernetes.local. A request with Host: nextcloud.nextcloud.svc.cluster.local returns HTTP 400.

fix:

# 1. allow private ClusterIPs (chart value, commit b6f0760)
#    requestFilteringAgent.allowPrivateIPAddress: true

# 2. use the Service port
kubectl -n nextcloud exec deploy/nextcloud -- \
  php occ config:app:set onlyoffice StorageUrl \
    --value="http://nextcloud.nextcloud.svc.cluster.local:8080/"

# 3. trust the internal DNS name
kubectl -n nextcloud exec deploy/nextcloud -- \
  php occ config:system:set trusted_domains 2 \
    --value=nextcloud.nextcloud.svc.cluster.local

kubectl -n euro-office patch cm documentserver --type merge \
  -p '{"data":{"ALLOW_PRIVATE_IP_ADDRESS":"true"}}'
kubectl -n euro-office rollout restart deploy/docservice deploy/converter

Verification from the document server pod:

kubectl -n euro-office exec deploy/docservice -c docservice -- \
  curl -sS -o /dev/null -w '%{http_code}\n' \
  http://nextcloud.nextcloud.svc.cluster.local:8080/status.php
# 200

7.10 Connector tarball has no vendor/ directory

The Euro-Office connector tarball from GitHub does not contain Composer dependencies. Enabling it manually produced:

Errionr:Cl/acsusst"oFmi_raepbpass/eo\nJlWyTo\fJfWiTc"e/nloitb/fDooucnudmentService.php:330

The Nextcloud app store package includes vendor/autoload.php. Installing the packaged app fixes it:

kubectl -n nextcloud exec deploy/nextcloud -- php occ app:install onlyoffice

This installed onlyoffice 9.15.1 (the app-store release compatible with Nextcloud 32) and kept the settings that were already stored in the database. See section 10 for the full version discussion.

7.11 Example editor: “The document security token is not correctly formed”

Opening a document from /example/ showed the browser error “The document security token is not correctly formed”. The document server logged:

[WARN]checkJwterror:name=JsonWebTokenErrormessage=jwtmustbeprovidedtoken=

The example image’s docker-entrypoint.sh sets:

"enable": ${JWT_ENABLED:-false}

JWT_SECRET is already injected from the euro-office-jwt secret, but JWT_ENABLED defaults to false. The example therefore rendered the editor config with token: "", while the document server has JWT enabled and rejected the empty token.

Fix: add the env vars to example.extraEnvVars (see section 5.3) and let the example StatefulSet roll:

example:
  extraEnvVars:
    - name: JWT_ENABLED
      value: "true"
    - name: JWT_HEADER
      value: Authorization
    - name: EXAMPLE_URL
      value: http://example:3000

The same rollout sets EXAMPLE_URL=http://example:3000 (no trailing slash). Without it the signed token’s document.url is http://localhost/example//download, which the document server cannot reach; with a trailing slash it is http://example:3000//download and returns 404.

After the rollout the editor page contains a signed JWT (verified against JWT_SECRET), and a CommandService.ashx request with that token is accepted by the document server. The example keeps documents inside the pod, so files created before the rollout are gone; create a new document after the restart. This was fixed in GitOps commits 57e97de (JWT) and f4e593b (EXAMPLE_URL).

7.12 Example app restarts and “File not found: new.docx”

The example stores documents in the container filesystem, not on a PVC. On 2026-10-29 the example container restarted after an unhandled error in POST /create (app.js:386): urllib failed to fetch a sample/external URL and data.length was read on undefined. The restart wiped the files, so an editor URL that was open before the restart returned:

Servererror:Filenotfound:new.docx

The pod restarted automatically and is healthy. Recreate the document with Create new → Blank; the blank route does not use /create. Avoid With sample content until the upstream /create handler is patched to check the urllib error. This is an example-app issue, not a document-server or Nextcloud issue.


8. Current resource usage

The final scheduling and resource requests are:

NamespaceWorkloadCPU requestMemory requestStorage
nfs-serverprovisioner50m64Mi8Gi (local-path)
euro-officePostgreSQL100m128Mi2Gi (local-path)
euro-officeRedis50m64Mi—
euro-officeRabbitMQ100m128Mi—
euro-officedocservice250m512Mi4Gi + 1Gi (NFS)
euro-officeconverter200m256Mishares NFS volumes
euro-officeproxy (sidecar)100m128Mi—
nextcloudNextcloud200m256Mi5Gi (local-path)

Placement:

NodeWorkloads
talos-node-1docservice, converter, redis
talos-node-2nextcloud
talos-node-3postgres, rabbitmq

The Euro-Office node selector is intentional: the 1.4 GB cluster-docs image is pulled once, and the proxy/docservice/converter share the NFS volumes.


9. Accessing the services

The management container’s DHCP address was 192.168.0.201 at install time. It changed to 192.168.0.192 on 2026-10-29. Replace .201 in the commands below with the current address; see access-sites.md for the current values and the socket/Ansible update procedure.

Add both hostnames to the client machine that runs the browser (not to the Proxmox host):

192.168.0.201euro-office.kubernetes.localnextcloud.kubernetes.local

192.168.0.201 is the management container, which proxies ports 80/443 to the Traefik NodePorts. Then open:

ServiceURL
Euro-Office Docshttp://euro-office.kubernetes.local/
Nextcloudhttp://nextcloud.kubernetes.local/

Verify from the management container without changing /etc/hosts:

# 302 -> http://euro-office.kubernetes.local/welcome/
curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'Host: euro-office.kubernetes.local' http://192.168.0.201/
# 302 -> http://nextcloud.kubernetes.local/login
curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'Host: nextcloud.kubernetes.local' http://192.168.0.201/

Follow the redirects with curl --resolve (section 12.3) to check the final pages.

9.1 Credentials

Retrieve them from the cluster; they are not stored in Git:

# Nextcloud admin
ssh root@192.168.0.201 \
  "kubectl -n nextcloud get secret nextcloud-admin \
     -o jsonpath='{.data.username}' | base64 -d; echo"
ssh root@192.168.0.201 \
  "kubectl -n nextcloud get secret nextcloud-admin \
     -o jsonpath='{.data.password}' | base64 -d; echo"

# Euro-Office JWT secret
ssh root@192.168.0.201 \
  "kubectl -n euro-office get secret euro-office-jwt \
     -o jsonpath='{.data.JWT_SECRET}' | base64 -d; echo"

10. Nextcloud ↔ Euro-Office integration

The connector is https://github.com/Euro-Office/eurooffice-nextcloud.

10.1 Version compatibility

The chart deployed Nextcloud 32.0.0. The current connector release (v11.x) requires Nextcloud 33–36, and the current app is published as eurooffice, which is not in the Nextcloud app store:

Error:Couldnotdownloadappeurooffice,itwasnotfoundontheappstore

The Euro-Office fork still has a v9.13.0 tag that supports Nextcloud 31–32. In that tag the internal app ID is still onlyoffice (the rename to eurooffice happened in v10, together with the Nextcloud 33 requirement).

The v9.13.0 tarball was installed manually first, but it does not contain vendor/, so the connector failed with Class "Firebase\JWT\JWT" not found. The app store package for onlyoffice does bundle vendor/ and is available for Nextcloud 32. Installing that package fixed the missing dependency and kept the settings already stored in the database:

kubectl -n nextcloud exec deploy/nextcloud -- \
  php occ app:install onlyoffice

Result: onlyoffice 9.15.1 enabled. This is the upstream ONLYOFFICE connector (the app store does not carry the Euro-Office fork); it speaks the same API and JWT protocol as Euro-Office Docs. The document server itself is Euro-Office 9.3.1.37.

If Euro-Office branding inside Nextcloud is required, use the fork’s v9.13.0 tarball plus the vendor/ directory from the app-store package. The functionality is the same; only the app name/branding differs.

10.2 Settings

POD=$(kubectl -n nextcloud get pod -l app.kubernetes.io/name=nextcloud \
  -o jsonpath='{.items[0].metadata.name}')

kubectl -n nextcloud exec "$POD" -- \
  php occ config:app:set onlyoffice DocumentServerUrl \
    --value="http://euro-office.kubernetes.local/"
kubectl -n nextcloud exec "$POD" -- \
  php occ config:app:set onlyoffice DocumentServerInternalUrl \
    --value="http://documentserver.euro-office.svc.cluster.local:8888/"
kubectl -n nextcloud exec "$POD" -- \
  php occ config:app:set onlyoffice StorageUrl \
    --value="http://nextcloud.nextcloud.svc.cluster.local:8080/"

JWT=$(kubectl -n euro-office get secret euro-office-jwt \
  -o jsonpath='{.data.JWT_SECRET}' | base64 -d)
kubectl -n nextcloud exec "$POD" -- \
  php occ config:app:set onlyoffice jwt_secret --value="$JWT"

DocumentServerUrl is what the browser uses; DocumentServerInternalUrl is what the Nextcloud server uses inside the cluster; StorageUrl is what the document server uses to fetch files from Nextcloud. Note the :8080 on StorageUrl: the Nextcloud chart’s Service exposes port 8080 and forwards to container port 80.

Nextcloud must also trust the internal DNS name used for those downloads:

kubectl -n nextcloud exec "$POD" -- \
  php occ config:system:set trusted_domains 2 \
    --value=nextcloud.nextcloud.svc.cluster.local

The connector writes the JWT in the Authorization header by default, which matches the chart’s jwt.header: Authorization default. No jwt_header override is needed.

Verify:

kubectl -n nextcloud exec "$POD" -- \
  php occ onlyoffice:documentserver --check

Expected:

Documentserverhttp://euro-office.kubernetes.local/version9.3.1.37issuccessfullyconnected

occ config:app:set prints the value it stores, including jwt_secret. Do not paste that terminal output into a ticket or commit.

10.3 Upgrading later

When Nextcloud is upgraded to 33 or newer, replace the connector with the current eurooffice app (v11.x) and use eurooffice instead of onlyoffice in every occ config:app:set command. The setting keys are unchanged.


11. Deviations from install-euro-office.md

Guide stepWhat was done insteadWhy
Helm repo euro-office.github.io / download.euro-office.comvendored chart from GitHubrepositories are gone / parked
NGINX IngressTraefikcluster already uses Traefik
cert-manager / Let’s EncryptHTTP onlyno cert-manager; homelab
NFS server provisionerinstalled as describedchart requires RWX
Bitnami PostgreSQL/Redis/RabbitMQsmall manifests with official imagesavoid retired Bitnami images, reduce footprint
Nextcloud + bundled MariaDBNextcloud + external PostgreSQLone database server, less memory/disk
apps/office/ subdirectorytop-level apps/Argo CD directory source does not recurse
Helm pre-upgrade hookdisabledArgo CD runs it on install; it fails
upstream schema URLpatched to Euro-Office/server/mainold URL returns 404

12. Verification

Verified on 2026-10-28 from the management container.

12.1 Argo CD

kubectl -n argocd get applications
NennrAuegoMrxioEotnt-cxol-fodfueidmcoeSSSSSYyyyyNnnnnCcccceeeeSddddTATUSHHHHHEeeeeAaaaaLllllTttttHhhhhyyyySTATUS

12.2 Workloads and storage

kubectl -n euro-office get pods,pvc
kubectl -n nextcloud get pods,pvc
kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded
PVCCapacityAccess modeStorageClass
euro-office/ds-files4GiRWXnfs
euro-office/ds-runtime-config1GiRWXnfs
euro-office/postgres-data2GiRWOlocal-path
nextcloud/nextcloud-nextcloud5GiRWOlocal-path
nfs-server/data-nfs-server-nfs-server-provisioner-08GiRWOlocal-path

12.3 HTTP endpoints

The management container does not resolve the *.kubernetes.local names, so curl --resolve is used to follow the redirects. These commands were recorded with the DHCP address of the time (.201); the current lease is .192 (see section 12.6):

curl -sSL --resolve euro-office.kubernetes.local:80:192.168.0.201 \
  -o /dev/null -w '%{http_code} %{url_effective}\n' \
  http://euro-office.kubernetes.local/
# 200 http://euro-office.kubernetes.local/welcome/

curl -sS --resolve euro-office.kubernetes.local:80:192.168.0.201 \
  -o /dev/null -w '%{http_code}\n' \
  http://euro-office.kubernetes.local/healthcheck
# 200

curl -sSL --resolve nextcloud.kubernetes.local:80:192.168.0.201 \
  -o /dev/null -w '%{http_code} %{url_effective}\n' \
  http://nextcloud.kubernetes.local/
# 200 http://nextcloud.kubernetes.local/login

The Euro-Office welcome page title is:

<title>Euro-Office Docs Community Edition</title>

12.4 Nextcloud ↔ Euro-Office

POD=$(kubectl -n nextcloud get pod -l app.kubernetes.io/name=nextcloud \
  -o jsonpath='{.items[0].metadata.name}')
kubectl -n nextcloud exec "$POD" -- php occ onlyoffice:documentserver --check
Documentserverhttp://euro-office.kubernetes.local/version9.3.1.37issuccessfullyconnected

The document server can also fetch status.php from Nextcloud over the internal Service:

kubectl -n euro-office exec deploy/docservice -c docservice -- \
  curl -sS -o /dev/null -w '%{http_code}\n' \
  http://nextcloud.nextcloud.svc.cluster.local:8080/status.php
# 200

12.5 Clean-up performed

12.6 Example application

The chart’s example was enabled with example.enabled: true (commit 3188ccc) and is the homelab equivalent of:

helm install documentserver onlyoffice/docs --set example.enabled=true
kubectl -n euro-office get statefulset example
kubectl -n euro-office get pod example-0 -o wide
# example   1/1   Running   talos-node-1

The public page returns HTTP 200:

curl -sSL --resolve euro-office.kubernetes.local:80:192.168.0.192 \
  -o /tmp/example.html -w '%{http_code} %{url_effective}\n' \
  http://euro-office.kubernetes.local/example/
# 200 http://euro-office.kubernetes.local/example/
grep -o '<title>[^<]*</title>' /tmp/example.html
# <title>Euro-Office Document editors</title>

The “Create new → Document” flow creates a document and redirects to the editor page:

# creates a document and redirects to the editor page
curl -sS -D - -o /dev/null \
  -H 'Host: euro-office.kubernetes.local' \
  'http://10.10.50.22:30080/example/editor?fileExt=docx'
# HTTP/1.1 302 Found
# Location: http://euro-office.kubernetes.local/example/editor?mode=edit&fileName=new%20(1).docx

curl -sSL --resolve euro-office.kubernetes.local:80:192.168.0.192 \
  -o /tmp/editor.html -w '%{http_code}\n' \
  'http://euro-office.kubernetes.local/example/editor?mode=edit&fileName=new%20(1).docx'
# 200
grep -o '<title>[^<]*</title>' /tmp/editor.html
# <title>new (1).docx - Euro-Office</title>

The example now runs with JWT_ENABLED=true and EXAMPLE_URL=http://example:3000. The editor page contains a signed JWT whose document.url is http://example:3000/download?...; a fetch from the docservice with Authorization: Bearer <token> returns 200. A CommandService.ashx request with the token returns 200 (the command-level error:6 is not a JWT error), and docservice logs no checkJwt error. See section 7.11.

The management container’s DHCP lease changed from 192.168.0.201 to 192.168.0.192 during verification. The traefik-ingress-http.socket / traefik-ingress-https.socket units were still bound to .201, so the public hostname refused connections while the Traefik NodePort at 10.10.50.22:30080 worked. The socket units and ansible2/hosts.yml were updated to .192 and the sockets restarted.


13. Backup target and Velero

Implemented on 2026-10-30. The full design, status, and limitations are in backup.md; the operational runbook is backup-restore-howto.md. No credentials are recorded here.

13.1 Proxmox LXC and external volume

Root SSH to the Proxmox host is denied, so Garage was installed in a dedicated privileged LXC rather than on the host:

ItemValue
VMID / hostname107 / garage-backup
Addresses192.168.0.224/24 on vmbr0, 10.10.50.2/24 on vmbr1
Root filesystem4 GiB on local-lvm
Memory1 GiB
Data volume500 GiB from externe-disk, mounted at /mnt/garage
Bootonboot=1
Entrypoint/usr/local/sbin/garage-net-init

externe-disk had to gain rootdir content so the LXC volume could be created; its content is now backup,rootdir,images. The LXC uses externe-disk:107/vm-107-disk-0.raw rather than a bind mount because the API token cannot create bind mounts.

The network entrypoint configures both interfaces, writes a resolver, and then execs /sbin/init. A container reboot was tested; both addresses, /mnt/garage, garage.service, and the metadata timer came back.

The LXC’s systemd reports degraded because host-style units such as apparmor, systemd-journald, systemd-tmpfiles, and nftables cannot run in this container. Do not add systemd namespace hardening to the Garage unit; it caused status=226/NAMESPACE. The minimal unit and the network script are stored in ansible2/files/backup/.

13.2 Garage

Garage v2.5.0 is installed at /usr/local/bin/garage; its configuration is /etc/garage.toml, with data on /mnt/garage/data and metadata in /var/lib/garage/meta. The service uses --single-node --default-bucket, which creates the velero bucket. The restic bucket was created explicitly and the default key was granted read/write/owner access. The internal S3 endpoint is http://10.10.50.2:3900 with path-style addressing.

A daily timer snapshots the metadata with SQLite’s online backup API into /mnt/garage/meta-snapshots and keeps 30 days. The Garage status was healthy (491.1 GiB capacity, 466.0 GiB available), both buckets were listed, and an unauthenticated curl to :3900 returned 403.

13.3 Velero

Velero chart 12.2.2 / server v1.18.2 is installed in the velero namespace with the AWS plugin v1.14.4 and CLI v1.18.4. The credentials are in the velero-credentials Secret; the values are in ansible2/files/backup/values-velero.yaml. The BackupStorageLocation default points at http://10.10.50.2:3900/velero and is Available.

The chart creates schedule/velero-daily at 02:00 UTC. It includes the application namespaces and backup, excludes the Kubernetes system namespaces and velero, and uses object-only backups (defaultVolumesToFsBackup: false, snapshotsEnabled: false).

Verification:

13.4 The local-path correction: restic

The smoke test exposed a design error: Velero/Kopia does not back up PVs whose source is hostPath, and the local-path provisioner uses hostPath PVs. A separate restic 0.18.1 DaemonSet was therefore added:

The NFS server’s backing store is a local-path volume, so backing up the NFS server node also covers the ds-files and ds-runtime-config client data. Snapshots were produced for talos-node-2 and talos-node-3 (and an empty snapshot for node 1), and a restore to a temporary hostPath directory restored 2386 files/dirs. The first automatic DaemonSet snapshots completed on 2026-10-30.

The restic password and AWS keys are in backup/restic-credentials; the password is required for restore and should be kept in a password manager.

13.5 PostgreSQL logical dump

The euro-office/postgres-dump CronJob runs daily at 01:30 UTC and writes pg_dumpall --clean --if-exists output to the 10 GiB local-path PVC euro-office/postgres-dumps. It keeps 14 days. A manual run completed with a 295 KiB dump, and the updated node-3 tree was captured in restic snapshot d612308f. The dump is included in restic because the PVC lives under /var/local-path-provisioner.

Forgejo still uses SQLite without a separate logical dump; Nextcloud and the database are not quiesced together. These are documented gaps.

13.6 Current status and gaps

Working: object backups, object restore, local-path snapshots, local-path restore test, PostgreSQL dump, Garage metadata snapshot, and LXC reboot persistence.

Still missing: an off-site copy of the external disk, Garage replication, Proxmox VM-level backups, application-consistent hooks, scheduled restore drills, TLS, and backup alerting. The external disk is currently a single failure domain.


14. Cluster monitoring (Prometheus and Grafana)

The monitoring Argo CD Application installs kube-prometheus-stack 92.17.0 from the public prometheus-community Helm repository. The Application is defined in ansible2/files/gitops/apps/monitoring.yaml; the chart values are inlined in the Application so the GitOps repository contains the full configuration.

14.1 Components and URLs

ComponentDetails
Grafanahttp://grafana.kubernetes.local; Traefik ingress
Prometheusinternal service monitoring-kube-prometheus-prometheus:9090
Alertmanagerinternal service; no receiver configured yet
node-exporterDaemonSet, one pod per Talos node
kube-state-metricsKubernetes object metrics
Prometheus Operatormanages Prometheus, Alertmanager, rules and monitors

Grafana uses the stable monitoring-grafana-admin Secret. It must exist before the first sync and is not stored in this repository. Create it with a random password:

kubectl create namespace monitoring --dry-run=client -o yaml | kubectl apply -f -
if ! kubectl -n monitoring get secret monitoring-grafana-admin >/dev/null 2>&1; then
  kubectl -n monitoring create secret generic monitoring-grafana-admin \
    --from-literal=admin-user=admin \
    --from-literal=admin-password="$(openssl rand -hex 24)"
fi

Create the Secret only once. Rotating it later does not update the password hash already stored in Grafana’s database.

Retrieve it with:

kubectl -n monitoring get secret monitoring-grafana-admin \
  -o jsonpath='{.data.admin-password}' | base64 -d; echo

No password is stored in this repository. See monitoring.md for the full runbook and password-reset caveats.

14.2 Values that matter

14.3 Verification

kubectl -n argocd get application monitoring
kubectl -n monitoring get pods,svc,ingress,pvc
curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'Host: grafana.kubernetes.local' http://192.168.0.192/login

Expected: the Application is Synced/Healthy, all pods are Running, the three monitoring PVCs are Bound, and Grafana returns 200. The monitoring/kube-prometheus-stack CRDs are installed with ServerSideApply=true; the initial sync therefore takes longer than the application charts.

Monitoring is intentionally not highly available: Prometheus, Grafana and Alertmanager each use a node-local local-path volume. There is no remote write, off-site copy, TLS or alert receiver yet.


15. Clean-up / re-run notes