Nextcloud Helm Chart

Nextcloud is a file sharing server that puts the control and security of your own data back into your hands.

TL;DR;

helm repo add nextcloud https://nextcloud.github.io/helm/
helm install my-release nextcloud/nextcloud

Quick Links

• Introduction
• Prerequisites
• Installing the Chart
• Uninstalling the Chart
• Upgrade / Breaking Changes
• Configuration
  • Ingress
    • Ingress Sticky-Sessions
      • NGINX Ingress-Controller
      • Traefik Ingress-Controller
      • HAProxy Ingress-Controller (Community-Version)
  • Database Configurations
  • Object Storage as Primary Storage Configuration
  • Persistence Configurations
  • Metrics Configurations
  • Headers set on NGINX
  • Probes Configurations
  • Collabora Configuration
  • Imaginary
• Cron jobs
• Using the nextcloud docker image auto-configuration via env vars
• Multiple config.php file
• Using nginx
  • Service discovery with nginx and ingress
• Preserving Source IP
• Hugepages
• HPA (Clustering)
• Adjusting PHP ini values
• Running occ commands
  • Putting Nextcloud into maintanence mode
  • Downloading models for recognize
• Backups
• Upgrades
• Troubleshooting
  • Logging
    • Changing the logging behavior
    • Viewing the logs
      • Exec into the kubernetes pod:
      • Then look for the nextcloud.log file with tail or cat:
      • Copy the log file to your local machine:
    • Sharing the logs

Introduction

This chart bootstraps an nextcloud deployment on a Kubernetes cluster using the Helm package manager.

You will also need a database compatible with Nextcloud. For more info, please see the Database Configuration section below.

If you want to persist data accross installs and upgrades, you’ll need to configure persistence. For more info, please see the Persistence Configuration section below.

We also package the following helm charts from Bitnami for you to optionally use:

Prerequisites

• Kubernetes 1.24+
• Persistent Volume provisioner support in the underlying infrastructure
• Helm >=3.7.0 (for subchart scope exposing)

Installing the Chart

To install the chart with the release name my-release:

helm repo add nextcloud https://nextcloud.github.io/helm/
helm install my-release nextcloud/nextcloud

The command deploys nextcloud on the Kubernetes cluster in the default configuration. The configuration section lists the parameters that can be configured during installation.

Tip: List all releases using helm list

Uninstalling the Chart

To uninstall/delete the my-release deployment:

helm delete my-release

The command removes all the Kubernetes components associated with the chart and deletes the release.

Upgrade / Breaking Changes

There is a Changelog of breaking changes here: CHANGELOG.md. You should read it bevore updating.

Configuration

The following table lists the configurable parameters of the nextcloud chart and their default values.

Ingress

Ingress Sticky-Sessions

For loadbalance over multiple Pods, it is useful to configure sticky session.

NGINX Ingress-Controller

To enable sticky sessions on that ingress controller you could set the following values in this helm-chart. For more information take a look in the ingress-controller documentation

ingress:
  annotations:
    nginx.ingress.kubernetes.io/affinity: cookie

Traefik Ingress-Controller

To enable sticky sessions on that ingress controller you could set the following values in this helm-chart. For more information take a look in the ingress-controller documentation

service:
  annotations:
    traefik.ingress.kubernetes.io/service.sticky.cookie: "true"

HAProxy Ingress-Controller (Community-Version)

To enable sticky sessions on that ingress controller you could set the following values in this helm-chart. For more infromation take a look in the ingress-controller documentation

ingress:
  annotations:
    haproxy-ingress.github.io/affinity: cookie

Database Configurations

By default, nextcloud will use a SQLite database. This is not recommended for production, but is enabled by default for testing purposes. When you are done testing, please set internalDatabase.enabled to false, and configure the externalDatabase parameters below.

For convenience, we packages the following Bitnami charts for databases (feel free to choose one below):

• Bitnami MariaDB chart
• Bitnami PostgreSQL chart

If you choose to use one of the prepackaged Bitnami helm charts, you must configure both the externalDatabase parameters, and the parameters for the chart you choose. For instance, if you choose to use the Bitnami PostgreSQL chart that we’ve prepackaged, you need to also configure all the parameters for postgresql. You do not need to use the Bitnami helm charts. If you want to use an already configured database that you have externally, just set internalDatabase.enabled to false, and configure the externalDatabase parameters below.

Is there a missing parameter for one of the Bitnami helm charts listed above? Please feel free to submit a PR to add that parameter in our values.yaml, but be sure to also update this README file :)

Object Storage as Primary Storage Configuration

Nextcloud allows to configure object storages like OpenStack Swift or Amazon Simple Storage Service (S3) or any compatible S3-implementation (e.g. Minio or Ceph Object Gateway) as primary storage replacing the default storage of files.

By default, files are stored in nextcloud/data or another directory configured in the config.php of your Nextcloud instance. This data directory might still be used for compatibility reasons)

Read more in the official docs.

Here are all the values you can currently configure in this helm chart to configure an Object Store as your Primary Storage.

Persistence Configurations

The Nextcloud image stores the nextcloud data and configurations at the /var/www/html paths of the container. Persistent Volume Claims are used to keep the data across deployments. This is known to work with GKE, EKS, K3s, and minikube. Nextcloud will not delete the PVCs when uninstalling the helm chart.

Metrics Configurations

We include an optional experimental Nextcloud Metrics exporter from xperimental/nextcloud-exporter.

Note:

For nextcloud to function correctly, you should specify the nextcloud.host parameter to specify the FQDN (recommended) or the public IP address of the nextcloud service.

Optionally, you can specify the service.loadBalancerIP parameter to assign a reserved IP address to the nextcloud service of the chart. However please note that this feature is only available on a few cloud providers (f.e. GKE).

To reserve a public IP address on GKE:

gcloud compute addresses create nextcloud-public-ip

The reserved IP address can be associated to the nextcloud service by specifying it as the value of the service.loadBalancerIP parameter while installing the chart.

Specify each parameter using the --set key=value[,key=value] argument to helm install. For example,

helm install --name my-release \
  --set nextcloud.username=admin,nextcloud.password=password,mariadb.auth.rootPassword=secretpassword \
    nextcloud/nextcloud

The above command sets the nextcloud administrator account username and password to admin and password respectively. Additionally, it sets the MariaDB root user password to secretpassword.

Alternatively, a YAML file that specifies the values for the above parameters can be provided while installing the chart. For example,

helm install --name my-release -f values.yaml nextcloud/nextcloud

Tip: You can use the default values.yaml

Headers set on NGINX

It is possible to set any additional header

Following keys are already set with this values:

• Referrer-Policy: no-referrer
• X-Content-Type-Options: nosniff
• X-Download-Options: noopen
• X-Frame-Options: SAMEORIGIN
• X-Permitted-Cross-Domain-Policies: none
• X-Robots-Tag: noindex, nofollow
• X-XSS-Protection: 1; mode=block

Maybe you like to set:

• Strict-Transport-Security: max-age=15768000; includeSubDomains; preload;

[!WARNING] Only add the preload option once you read about the consequences in https://hstspreload.org/. This option will add the domain to a hardcoded list that is shipped in all major browsers and getting removed from this list could take several months.

Probes Configurations

The nextcloud deployment includes a series of different probes you can use to determine if a pod is ready or not. You can learn more in the Configure Liveness, Readiness and Startup Probes Kubernetes docs.

[!Note] If you are getting errors on initialization (such as Fatal error: require_once(): Failed opening required '/var/www/html/lib/versioncheck.php', but you can get other errors as well), a good first step is to try and enable the startupProbe and/or increase the initialDelaySeconds for the livenessProbe and readinessProbe to something much greater (consider using 120 seconds instead of 10. This is an especially good idea if your cluster is running on older hardware, has a slow internet connection, or you’re using a slower storage class, such as NFS that’s running with older disks or a slow connection.

Collabora Configuration

This section provides options to enable and configure the Collabora Online server within your deployment. Please ensure to review the Collabora Online Helm chart documentation for additional details and recommended values.

Note:

You may need to uncomment collabora.collabora.aliasgroups and collabora.collabora.extra_params, depending on your setup. You may also need to set collabora.collabora.server_name. If left empty, it’s derived from the request, so please set it if it doesn’t work.

If you have both Nextcloud and Collabora behind a reverse proxy with HTTPS, collabora.collabora.aliasgroups should match your Nextcloud domain and collabora.collabora.server_name (if needed) should match your Collabora domain.

For more information, please check the Collabora documentation.

Imaginary

We include an optional external preview provider from h2non/imaginary.

[!Note] You also need to setup nextcloud, to use imaginary

nextcloud:
  defaultConfigs:
    imaginary.config.php: true

imaginary:
  enabled: true

Cron jobs

To execute background tasks by using system cron instead of default Ajax cron, set cronjob.enabled parameter to true. Background jobs are important for tasks that do not necessarily need user intervention, but still need to be executed frequently (cleaning up, sending some notifications, pulling RSS feeds, etc.).

Enabling this option will create a sidecar container in the Nextcloud pod, which will start a crond daemon responsible for running the Nextcloud cron.php script. At first launch, the background jobs mode in your Nextcloud basic settings will automatically be set to Cron.

You can also set cronjob.type to cronjob to instead use a Kubernetes native CronJob. One advantage of this is that it can run as non-root when compared to the crond sidecar.

Using the nextcloud docker image auto-configuration via env vars

The nextcloud/docker image provides an auto-configuration via environment variables. See their docs for more info.

Multiple config.php file

Nextcloud supports loading configuration parameters from multiple files. You can add arbitrary files ending with .config.php in the config/ directory. See documentation. For example, to enable image and document previews:

nextcloud:
  configs:
    previews.config.php: |-
      <?php
      $CONFIG = array (
        'enable_previews' => true,
        'enabledPreviewProviders' => array (
          'OC\Preview\Movie',
          'OC\Preview\PNG',
          'OC\Preview\JPEG',
          'OC\Preview\GIF',
          'OC\Preview\BMP',
          'OC\Preview\XBitmap',
          'OC\Preview\MP3',
          'OC\Preview\MP4',
          'OC\Preview\TXT',
          'OC\Preview\MarkDown',
          'OC\Preview\PDF'
        ),
      );

Using nginx

To use nginx instead of apache to serve nextcloud, Set the following parameters in your values.yaml:

# This Generates an image tag using the chart's app version
# e.g. if the app version is 25.0.3, the image tag will be 25.0.3-fpm
image:
  flavor: fpm
  # You can also specify a tag directly. this version is an example:
  # tag: 25.0.3-fpm

# this deploys an nginx container within the nextcloud pod
nginx
  enabled: true

Service discovery with nginx and ingress

For service discovery (CalDAV, CardDAV, webfinger, nodeinfo) to work you need to add redirects to your ingress. If you use the ingress-nginx you can use the following server snippet annotation:

ingress:
  annotations:
    nginx.ingress.kubernetes.io/server-snippet: |-
      server_tokens off;
      proxy_hide_header X-Powered-By;
      rewrite ^/.well-known/webfinger /index.php/.well-known/webfinger last;
      rewrite ^/.well-known/nodeinfo /index.php/.well-known/nodeinfo last;
      rewrite ^/.well-known/host-meta /public.php?service=host-meta last;
      rewrite ^/.well-known/host-meta.json /public.php?service=host-meta-json;
      location = /.well-known/carddav {
        return 301 $scheme://$host/remote.php/dav;
      }
      location = /.well-known/caldav {
        return 301 $scheme://$host/remote.php/dav;
      }
      location = /robots.txt {
        allow all;
        log_not_found off;
        access_log off;
      }
      location ~ ^/(?:build|tests|config|lib|3rdparty|templates|data)/ {
        deny all;
      }
      location ~ ^/(?:autotest|occ|issue|indie|db_|console) {
        deny all;
      }

Preserving Source IP

• Make sure your loadbalancer preserves source IP, for bare metal, metalb does and klipper-lb doesn’t.
• Make sure your Ingress preserves source IP. If you use ingress-nginx, add the following annotations:

ingress:
  annotations:
   nginx.ingress.kubernetes.io/enable-cors: "true"
   nginx.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For"

• The next layer is nextcloud pod’s nginx container. In in your values.yaml, if nextcloud.tag has fpm in it, or image.flavor is set to fpm, this can be left at default
• Add some PHP config for nextcloud as mentioned above in multiple config.phps section:

  configs:
    proxy.config.php: |-
      <?php
      $CONFIG = array (
        'trusted_proxies' => array(
          0 => '127.0.0.1',
          1 => '10.0.0.0/8',
        ),
    'forwarded_for_headers' => array('HTTP_X_FORWARDED_FOR'),
    );

Hugepages

If your node has hugepages enabled, but you do not map any into the container, it could fail to start with a bus error. This is due to your webserver attempting to memory map a file and use hugepages. This can happen in both the apache and fpm images. The fix is to either disable huge pages on the node or map hugepages into the container:

nextcloud:
  extraVolumes:
    - name: hugepages
      emptyDir:
        medium: HugePages-2Mi
  extraVolumeMounts:
    - name: hugepages
      mountPath: /dev/hugepages
resources:
  requests:
    hugepages-2Mi: 500Mi
    # note that Kubernetes currently requires cpu or memory requests and limits before hugepages are allowed.
    memory: 500Mi
  limits:
    # limit and request must be the same for hugepages. They are a fixed resource.
    hugepages-2Mi: 500Mi
    # note that Kubernetes currently requires cpu or memory requests and limits before hugepages are allowed.
    memory: 1Gi

HPA (Clustering)

If you want to have multiple Nextcloud containers, regardless of dynamic or static sizes, you need to use shared persistence between the containers.

Minimum cluster compatible persistence settings:

persistence:
  enabled: true
  accessMode: ReadWriteMany

Adjusting PHP ini values

Sometimes you may need special php.ini values. For instance, perhaps your setup requires a bit more memory. You can add additional php.ini files in the values.yaml by providing nextcloud.phpConfigs.NAME_OF_FILE. Here’s an examples:

nextcloud:
  phpConfigs:
    zz-memory_limit.ini: |-
      memory_limit=512M

[!Note] Be sure to prefix your file name with zz to ensure it is loaded at the end.

Running occ commands

Sometimes you need to run an occ command on the Nextcloud container directly. You can do that by running commands as the user www-data via the kubectl exec command.

# $NEXTCLOUD_POD should be the name of *your* nextcloud pod :)
kubectl exec $NEXTCLOUD_POD -- su -s /bin/sh www-data -c "php occ myocccomand"

Here are some examples below.

Putting Nextcloud into maintanence mode

Some admin actions require you to put your Nextcloud instance into maintanence mode (e.g. backups):

# $NEXTCLOUD_POD should be the name of *your* nextcloud pod :)
kubectl exec $NEXTCLOUD_POD -- su -s /bin/sh www-data -c "php occ maintenance:mode --on"

Downloading models for recognize

Recognize requires you to download models before using it:

# $NEXTCLOUD_POD should be the name of *your* nextcloud pod :)
kubectl exec $NEXTCLOUD_POD -- su -s /bin/sh www-data -c "php occ recognize:download-models"

Backups

Check out the official Nextcloud backup docs. For your files, if you’re using persistent volumes, and you’d like to back up to s3 backed storage (such as minio), consider using k8up or velero.

Upgrades

Since this chart utilizes the nextcloud/docker image, provided you are using persistent volumes, upgrades of your Nextcloud server are handled automatically from one version to the next, however, you can only upgrade one major version at a time. For example, if you want to upgrade from version 25 to 27, you will have to upgrade from version 25 to 26, then from 26 to 27. Since our docker tag is set via the appVersion in Chart.yaml, you’ll need to make sure you gradually upgrade the helm chart if you have missed serveral app versions.

⚠️ Before Upgrading Nextcloud or the attached database, always make sure you take backups!

After an upgrade, you may have missing indices. To fix this, you can run:

# where NEXTCLOUD_POD is *your* nextcloud pod
kubectl exec -it $NEXTCLOUD_POD -- su -s /bin/sh www-data -c "php occ db:add-missing-indices"

Troubleshooting

Logging

The nextcloud instance deployed by this chart doesn’t currently create a log file locally inside the container. Examples scenarios to change this behavior include:

• Triaging mailserver issues
• Any time you’re confused by server behavior and need more context
• Before submitting a GitHub Issue (you can include relevant log messages that way)

Changing the logging behavior

To change the logging behavior, modify your logging.config.php in your values.yaml under the nextcloud.configs section like so:

nextcloud:
  configs:
    logging.config.php: |-
      <?php
      $CONFIG = array (
        'log_type' => 'file',
        'logfile' => 'nextcloud.log',
        'loglevel' => 0,
        'logdateformat' => 'F d, Y H:i:s'
        );

loglevel corresponds to the detail of the logs. Valid values are:

More information about Nextcloud logging

Viewing the logs

To view logs after changing the logging behavior, you can exec into the Kubernetes pod, or copy them to your local machine.

Exec into the kubernetes pod:

kubectl exec --stdin --tty nextcloud-pod-name-random-chars -- /bin/sh

Then look for the nextcloud.log file with tail or cat:

cat nextcloud.log
tail -f nextcloud.log

Copy the log file to your local machine:

kubectl cp default/nextcloud-pod-name-random-chars:nextcloud.log ./my-local-machine-nextcloud.log

Sharing the logs

Remember to anonymize your logs and snippets from your pod before sharing them with the internet. Kubernetes secrets, even Sealed ones, live in plaintext env variables on your running containers, and log messages can include other information that should stay safely with you.