Skip to content
This repository was archived by the owner on Aug 19, 2026. It is now read-only.

caching_configuration.adoc

Latest commit

 

History

History
281 lines (198 loc) · 12.2 KB

caching_configuration.adoc

File metadata and controls

281 lines (198 loc) · 12.2 KB
Raw

Memory Caching

Table of Contents

Introduction

You can significantly improve ownCloud server performance by using memory caching. This is the process of storing frequently requested objects in memory for faster retrieval later. There are two types of memory caching available:

A PHP opcode Cache (OPcache)

An opcode cache stores compiled PHP scripts (opcodes) so they don’t need to be parsed and compiled every time they are called. These compiled PHP scripts are stored in shared memory on the server on which they’re compiled.

A Data Cache

A data cache stores copies of data, templates, and other types of information-based files. Depending on the cache implementation, it can be either local or specific to one server or distributed across multiple servers. This cache type is ideal when you have a scale-out installation.

In addition, we suggest to use External Transactional File Locking which reduces load on the database significantly.

Supported Caching Backends

The caching backends supported by ownCloud are:

  • Opcache
    This is an opcode cache only and does not cache any data. Opcache is bundled with PHP and part of the Docker image.

  • APCu
    This is a data cache only and does not cache any opcode. APCu is part of the Docker image.

  • Redis
    This is an in-memory data structure store (cache) for single and multi-server ownCloud installations, which provides file locking and can be set up in local or distributed environments. The required php-redis extension is already part of the Docker image. Redis is used in the Docker Compose deployment example. For details see the Installing With Docker documentation.

  • Memcached
    This is a distributed cache for multi-server ownCloud installations and has very limited file locking capabilities.
    Using Memcached for distributed locking is generally not recommended. Because its nodes do not communicate with each other and data isn’t persistent, locks can be released unexpectedly or lost entirely if a server restarts. For reliable locking, Redis is the industry standard. + See the following page to learn more about the Redis vs. Memcached – 2021 Comparison.

Note

You may use both a local and a distributed cache. The recommended ownCloud caches are APCu and Redis. If you do not install and enable a local memory cache you will see a warning on your ownCloud admin page. If you either enable Redis or Memcached, the distributed cache will be set automatically to the respective backend.

Cache Directory Location

The cache directory defaults to <mount-point>/files/$user/cache and $user is the current ownCloud user. You may use the OWNCLOUD_CACHE_PATH environment variable for different locations.

Cache Types

Opcache

Opcache is enabled by default in the Docker image. To check this, you need to access the container’s shell and run the following PHP command:

docker exec -it owncloud_server /bin/bash

php -r 'phpinfo();' | grep opcache.enable

APCu

The easiest cache to use is APCu, because it is a pure data cache, very fast as it is memory-based only. If defined, nothing needs to be configured.

Redis

Redis is an excellent modern memory cache to use for both distributed caching and as a local cache for transactional file locking, because it guarantees that cached objects are available for as long as they are needed. Redis is very configurable; consult the Redis documentation to learn more.

Note

Authentication with Redis:

  • ownCloud does support the password protection available with current Redis versions which can be configured with environment variables.

  • With Redis version 6 upwards, a new authentication mechanism has been introduced named ACL (Access Control Lists). ownCloud does currently not support Redis ACLs.

Redis Performance Consideration

  • Because Redis writes data to disk, it is recommended to use a high performance backend like SSD.

Additional Notes for Redis vs. APCu on Memory Caching

  • APCu is faster at local caching than Redis since APCu is memory-based only.

  • If you have enough memory, use APCu for in memory caching and Redis for file locking.

  • If you are limited in memory or only want to have one caching backend, use Redis for both.

Clearing the Redis Cache

The Redis cache can be flushed from the command-line using the redis-cli tool. To do so, you first must enter the Redis containers shell and use the following command example:

redis-cli
SELECT <dbIndex>
FLUSHDB

Please note that <dbIndex> is the index number of the Redis database where the cache is stored. It is zero by default at ownCloud. To check what yours is currently set to for ownCloud, check if the OWNCLOUD_REDIS_DB environment variable has been configured. For more details see the Memory caching backend configuration documentation.

Note
 Out of the box, every Redis instance supports 16 databases so <dbIndex> has to be set between 0 and 15.

Please read more about the instructions for the select and flushdb command.

Memcached

Memcached is a reliable old-timer for shared caching on distributed servers. It performs well with ownCloud with one exception: it is not suitable to use with Transactional File Locking. This is because it does not store locks, and data can disappear from the cache at any time. Given that, Redis is the best memory cache to use.

Note
 The memcached PHP extension is already embedded in the Docker image and enabled.

Configuring Memory Caching

Memory caches must be provided and explicitly configured in ownCloud by:

  1. When using Redis or Memcached, it must be provided by either as described in the Docker Compose example of the installation documentation or by other means.

  2. Configuring the caches used.

Note that the OWNCLOUD_MEMCACHE_LOCKING environment variable corresponds to the configuration setting memcache.locking. However, there is no counterpart for the setting memcache.distributed, as it is set automatically based on the caching type enabled.

See the Memory caching backend configuration for an overview of all possible config parameters, as the examples below only show basic configuration settings.

Opcache Configuration

Opcache is already enabled and configured with the Docker image provided.

APCu Configuration

The environment variable that defines the memory cache has a default value, which is used if nothing else is configured. This value is described below:

OWNCLOUD_MEMCACHE_LOCAL='\OC\Memcache\APCu'

Redis Configuration

If you select Redis, you must enable it via environment variables. The example value for the host setting assumes that you have used the ownCloud Docker Compose deployment example. Adapt this value for your setup.

OWNCLOUD_REDIS_ENABLED=true
OWNCLOUD_REDIS_HOST=redis
OWNCLOUD_REDIS_PORT=6379

  • If Redis is not enabled, none of the other Redis configurations will be taken into account.

  • If Redis is enabled, two additional configurations are set automatically:

    'memcache.locking' => '\OC\Memcache\Redis'
'memcache.distributed' => '\OC\Memcache\Redis'

Transactional File Locking prevents simultaneous file saving. It is enabled by default and uses the database to store the locking data. This places a significant load on your database. It is recommended to use a cache backend instead. We recommend adding the following for best performance. This enables External Transactional File Locking based on Redis:

OWNCLOUD_FILELOCKING_ENABLED=true
OWNCLOUD_MEMCACHE_LOCAL='\OC\Memcache\Redis'
Caution
 ownCloud provides many configuration options for Redis, including enhanced security features such as password protection. See the Redis security URL and the ownCloud environment variables for more details.

Memcached Configuration

If you select Memcached, you must enable it via environment variables. The example value for the host setting assumes that you have used the ownCloud Docker Compose deployment example. Adapt this value for your setup.

OWNCLOUD_MEMCACHED_ENABLED=true
OWNCLOUD_MEMCACHED_HOST=memcached
OWNCLOUD_MEMCACHED_PORT=11211

Additional memcached options can be set with the environment variable OWNCLOUD_MEMCACHED_OPTIONS.

  • If Memcached is not enabled, none of the other Memcached configurations will be taken into account.

  • If Memcached is enabled, two additional configurations are set automatically:

    'memcache.locking' => '\OC\Memcache\Memcached'
'memcache.distributed' => '\OC\Memcache\Memcached'

Clearing the Memcached Cache

The Memcached cache can be flushed from the command line, using a range of common Linux/Unix tools including netcat and telnet. The following example uses telnet to log in, run the flush_all command, and log out:

telnet <memcached-hostname> 11211
flush_all
quit

Deployment Type Configuration Examples

These examples provide an overview. Adapt them to suit your environment and needs.

Private Home Server With Low Access Rates

Use APCu for local caching, file locking is not mandatory, Redis is not required and can be removed from the deployment example.

OWNCLOUD_MEMCACHE_LOCAL='\OC\Memcache\APCu'

Small Server

Use APCu for local caching and Redis for file locking.

OWNCLOUD_REDIS_ENABLED=true
OWNCLOUD_REDIS_HOST=redis
OWNCLOUD_FILELOCKING_ENABLED=true
OWNCLOUD_MEMCACHE_LOCAL='\OC\Memcache\APCu'

Small Organization, Single-server Setup

Use Redis for local caching and for file locking.

OWNCLOUD_REDIS_ENABLED=true
OWNCLOUD_REDIS_HOST=redis
OWNCLOUD_FILELOCKING_ENABLED=true
OWNCLOUD_MEMCACHE_LOCAL='\OC\Memcache\Redis'

Large Organization, Clustered Setup

Use Redis for everything except a local memory cache.

OWNCLOUD_REDIS_ENABLED=true
OWNCLOUD_REDIS_SEEDS='host_1:port,host_2:port'
OWNCLOUD_FILELOCKING_ENABLED=true
OWNCLOUD_MEMCACHE_LOCAL='\OC\Memcache\APCu'

See Define Redis Cluster connection details when using a Redis clustered setup.

Caching Exceptions

If ownCloud is configured to use Redis as a memory cache, you may encounter issues with functionality. When these occur, it is usually a result of PHP being incorrectly configured or the relevant PHP extension not being available.

In the table below, you can see all of the known reasons for reduced or broken functionality related to caching.

Setup/Configuration Result

If file locking is enabled, but the locking cache class is missing, then an exception will appear in the web UI

The application will not be usable

All enabled, but the Redis server is not running

The application will be usable. But any file operation will return a "500 Redis went away" exception