diff --git a/admin_manual/configuration/performance_tips.rst b/admin_manual/configuration/performance_tips.rst index 031d39656..8aaf9ddd9 100644 --- a/admin_manual/configuration/performance_tips.rst +++ b/admin_manual/configuration/performance_tips.rst @@ -43,3 +43,173 @@ Memcached servers must be specified in the "memcached_servers" array in ownCloud MySQL or MariaDB should be preferred because of the `performance limitations of SQLite with highly concurrent applications `_, like ownCloud. On large instances you could consider `running MySQLTuner `_ to optimize the database. + +----------------------------------- + +Nginx: caching owncloud gallery thumbnails with fastcgi_cache_purge +=================================================================== + +| One of the optimisations for owncloud when using Nginx as webserver is to combine FastCGI caching with "Cache Purge", a `3rdparty Nginx module `_ that adds the ability to purge content from `FastCGI`, `proxy`, `SCGI` and `uWSGI` caches. This mechanism speeds up thumbnail presentation as it shifts requests to Nginx and minimizes php invocations which else would take place for every thumbnail presented every time. +| The following procedure is based on an Ubuntu 14.04 system. You may need to adopt it according your OS type and release. +| **Note I:** +| Unlike Apache, Nginx does not dynamically load modules. All modules needed, must be compiled into Nginx. This is one of the reasons for Nginx´s performance. +| **Note II:** +| It is expected to have an already running Nginx installation with a working configuration set up like described in the owncloud documentation. + +Nginx module check +------------------ +| As a first step, it is necessary to check if your Nginx installation has the ``nginx cache purge`` module compiled in. +| +| ``nginx -V 2>&1 | grep ngx_cache_purge -o`` +| +| If your output contains ``ngx_cache_purge``, you can continue with the configuration, else you need to manually compile Nginx with the module needed. + +Compile Nginx with the ``nginx-cache-purge`` module +--------------------------------------------------- + +1. | *Preparation* + | ``cd /opt`` + | ``wget http://nginx.org/keys/nginx_signing.key`` + | ``sudo apt-key add nginx_signing.key`` + | ``sudo vi /etc/apt/sources.list.d/nginx.list`` + | + | Add following lines (in case, replace ``{trusty}`` by your distribution name): + | ``deb http://nginx.org/packages/mainline/ubuntu/ trusty nginx`` + | ``deb -src http://nginx.org/packages/mainline/ubuntu/ trusty nginx`` + | + | Then do a + | ``sudo apt-get update`` + | + | **Note:** + | If you're not overly cautious and wish to install the latest and greatest Nginx packages and features, you may have to install Nginx from its mainline repository. + | From the Nginx homepage: "In general, you should deploy Nginx from its mainline branch at all times." + | + | If you would like to use standard Nginx from the latest mainline branch but without compiling in any additional modules, just run ``sudo apt-get install nginx``. + | + +2. | *Download the Nginx source from the ppa repository* + | ``cd /opt`` + | ``sudo apt-get build-dep nginx`` + | ``sudo apt-get source nginx`` + | + +3. | *Download module(s) to be compiled in and configure compiler arguments* + | ``ls -la`` + | + | Please replace ``{release}`` with the release downloaded + | ``cd /opt/nginx-{release}/debian`` + | + | If folder "modules" is not present, do: + | ``sudo mkdir modules`` + | ``cd modules`` + | ``sudo git clone https://github.com/FRiCKLE/ngx_cache_purge.git`` + | ``sudo vi /opt/nginx-{release}/debian/rules`` + | + | If not present, add the following line at the top under ``#export DH_VERBOSE=1``: + | ``MODULESDIR = $(CURDIR)/debian/modules`` + | + | And the end of `every` ``./configure`` command add: + | ``--add-module=$(MODULESDIR)/ngx_cache_purge`` + | + | Don't forget to escape preceeding lines with a backslash ``\``. + | The parameters may now look : + | ``$(WITH_SPDY) \`` + | ``--with-cc-opt="$(CFLAGS)" \`` + | ``--with-ld-opt="$(LDFLAGS)" \`` + | ``--with-ipv6 \`` + | ``--add-module=$(MODULESDIR)/ngx_cache_purge`` + | + +4. | *Compile and install Nginx* + | ``cd /opt/nginx-{release}`` + | ``sudo dpkg-buildpackage -uc -b`` + | ``ls -la /opt`` + | ``sudo dpkg --install /opt/nginx_{release}~{distribution}_amd64.deb`` + | + +5. | *Check if the compilation and installation of the* ``ngx_cache_purge`` *module was successful* + | ``nginx -V 2>&1 | grep ngx_cache_purge -o`` + | + | It should show now: ``ngx_cache_purge`` + | + | Show Nginx version including all features compiled and installed: + | ``nginx -V 2>&1 | sed s/" --"/"\n\t--"/g`` + | + +6. | *Mark Nginx to be blocked from further updates via* ``apt-get`` + | ``sudo dpkg --get-selections | grep nginx`` + | + | For eyery nginx component listed do a: + | ``sudo apt-mark hold `` + | + +7. | *Regular checks for nginx updates* + | Do a regular visit on the `Nginx news page `_ and proceed in case of updates with item 2 to 5 + +Configure Nginx with the ``nginx-cache-purge`` module +----------------------------------------------------- +1. | *Preparation* + | Create a directory where Nginx will save the cached thumbnails. Use any path that fits to your environment. Replace ``{path}`` with the path used, example path below: + | ``sudo mkdir -p /usr/local/tmp/cache`` + | + +2. | *Configuration* + | ``sudo vi /etc/nginx/sites-enabled/{your-owncloud-nginx-config-file}`` + | + | Note: the ``keys_zone`` / ``fastcgi_cache`` name and the ``{path}`` must be unique to each instance of owncloud serverd with Nginx ! + | + | Add at the *beginning*, but *outside* the ``server{}`` block: + | ``fastcgi_cache_path {path} levels=1:2 keys_zone=OWNCLOUD:100m inactive=60m;`` + | + | Add *inside* the ``server{}`` block, as an example of a configuration: + | + | ``set $skip_cache 1;`` + | + | ``# POST requests and urls with a query string should always go to PHP`` + | ``if ($request_uri ~* "thumbnail.php") {`` + | ``set $skip_cache 0;`` + | ``}`` + | + | ``fastcgi_cache_key "$scheme$request_method$host$request_uri";`` + | ``fastcgi_cache_use_stale error timeout invalid_header http_500;`` + | ``fastcgi_ignore_headers Cache-Control Expires Set-Cookie;`` + | + | ``location ~ \.php(?:$|/) {`` + | ``fastcgi_split_path_info ^(.+\.php)(/.+)$;`` + | ``try_files $fastcgi_script_name =404;`` + | + | ``include fastcgi_params;`` + | ``fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;`` + | ``fastcgi_param PATH_INFO $fastcgi_path_info;`` + | ``fastcgi_param HTTPS on;`` + | ``fastcgi_pass php-handler;`` + | + | ``fastcgi_cache_bypass $skip_cache;`` + | ``fastcgi_no_cache $skip_cache;`` + | ``fastcgi_cache OWNCLOUD;`` + | ``fastcgi_cache_valid 60m;`` + | ``}`` + | + | Note regarding the ``fastcgi_pass`` parameter: + | Use whatever fits your configuration. In the example above, a ``upstream`` was defined in a global configuration file. + | This then can look like: + | + | ``upstream php-handler {`` + | ``server 127.0.0.1:9000;`` + | ``# or`` + | ``#server unix:/var/run/php5-fpm.sock;`` + | ``}`` + | + +3. | *Test the configuration* + | ``sudo service nginx restart`` + + * | Open your browser and clear your cache. + + * | Logon to your owncloud instance, open the gallery app, move thru your folders + | and watch while the thumbs are generated for the first time. + * | You may also watch with eg. ``htop`` your system load while the thumbnails are processed. + * | Goto another app or logout and relogon. + * | Open the gallery app again and browse to the folders you accessed before. + | Your thumbnails should appear more or less immediately. + * | ``htop`` will not show up additional load while processing, compared to the high load before.