From a131b4d3e61f7c96bc9319c98cff987d66a9fc0d Mon Sep 17 00:00:00 2001 From: Morris Jobke Date: Sun, 14 May 2017 13:05:59 -0500 Subject: [PATCH 1/2] Remove Nginx section about compiling a module Signed-off-by: Morris Jobke --- admin_manual/installation/nginx.rst | 4 +- admin_manual/installation/nginx_examples.rst | 258 ------------------- 2 files changed, 2 insertions(+), 260 deletions(-) diff --git a/admin_manual/installation/nginx.rst b/admin_manual/installation/nginx.rst index b6640d80c..f313bd75b 100644 --- a/admin_manual/installation/nginx.rst +++ b/admin_manual/installation/nginx.rst @@ -33,7 +33,7 @@ your nginx installation. } server { - listen 443 ssl; + listen 443 ssl http2; server_name cloud.example.com; ssl_certificate /etc/ssl/nginx/cloud.example.com.crt; @@ -161,7 +161,7 @@ your nginx installation. } server { - listen 443 ssl; + listen 443 ssl http2; server_name cloud.example.com; ssl_certificate /etc/ssl/nginx/cloud.example.com.crt; diff --git a/admin_manual/installation/nginx_examples.rst b/admin_manual/installation/nginx_examples.rst index a502d961d..d5974d088 100644 --- a/admin_manual/installation/nginx_examples.rst +++ b/admin_manual/installation/nginx_examples.rst @@ -73,261 +73,3 @@ block shown above not located **below** the: block. Other custom configurations like caching JavaScript (.js) or CSS (.css) files via gzip could also cause such issues. - -Performance Tuning -================== - -* `nginx (<1.9.5) `_ -* `nginx (+1.9.5) `_ - -To use http_v2 for nginx you have to check two things: - -1.) be aware that this module is not built in by default due to a dependency -to the openssl version used on your system. It will be enabled with the -``--with-http_v2_module`` configuration parameter during compilation. The -dependency should be checked automatically. You can check the presence of -http_v2 with ``nginx -V 2>&1 | grep http_v2 -o``. An example of how to -compile nginx can be found in section "Configure nginx with the -``nginx-cache-purge`` module" below. - -2.) When you have used SPDY before, the nginx config has to be changed from -``listen 443 ssl spdy;`` to ``listen 443 ssl http2;`` - -nginx: caching Nextcloud gallery thumbnails -=========================================== - -One of the optimizations for Nextcloud when using nginx as the Web server 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 otherwise would take place for every thumbnail presented -every time. - -The following procedure is based on an Ubuntu 14.04 system. You may need to -adapt it according your OS type and release. - -.. note:: - 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. It is expected to have an already running nginx installation - with a working configuration set up as described in the Nextcloud - 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, otherwise 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 the following lines (if different, 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 run ``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 at the end of every ``configure`` command add:: - - --add-module=$(MODULESDIR)/ngx_cache_purge - -Don't forget to escape preceding lines with a backslash ``\``. -The parameters may now look like:: - - --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 now show: ``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 every nginx component listed run ``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 items 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}`` in this example with - your path created: - -:: - - sudo mkdir -p /usr/local/tmp/cache - -2. **Configuration** - -:: - - sudo vi /etc/nginx/sites-enabled/{your-nextcloud-nginx-config-file} - -Add at the *beginning*, but *outside* the ``server{}`` block: - -.. code-block:: nginx - - # cache_purge - fastcgi_cache_path {path} levels=1:2 keys_zone=NEXTCLOUD:100m inactive=60m; - map $request_uri $skip_cache { - default 1; - ~*/thumbnail.php 0; - ~*/apps/galleryplus/ 0; - ~*/apps/gallery/ 0; - } - -.. note:: Please adopt or delete any regex line in the ``map`` block according - your needs and the Nextcloud version used. - As an alternative to mapping, you can use as many ``if`` statements in - your server block as necessary: - - .. code-block:: nginx - - set $skip_cache 1; - if ($request_uri ~* "thumbnail.php") { set $skip_cache 0; } - if ($request_uri ~* "/apps/galleryplus/") { set $skip_cache 0; } - if ($request_uri ~* "/apps/gallery/") { set $skip_cache 0; } - -Add *inside* the ``server{}`` block, as an example of a configuration: - -.. code-block:: nginx - - # cache_purge (with $http_cookies we have unique keys for the user) - fastcgi_cache_key $http_cookie$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)(/.*)$; - - 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_request_buffering off; #Available since nginx 1.7.11 - - # cache_purge - fastcgi_cache_bypass $skip_cache; - fastcgi_no_cache $skip_cache; - fastcgi_cache NEXTCLOUD; - fastcgi_cache_valid 60m; - fastcgi_cache_methods GET HEAD; - } - -.. note:: Note regarding the ``fastcgi_pass`` parameter: - Use whatever fits your configuration. In the example above, an ``upstream`` - was defined in an nginx global configuration file. - This may look like: - - .. code-block:: nginx - - upstream php-handler { - server unix:/var/run/php5-fpm.sock; - # or - # server 127.0.0.1:9000; - } - -3. **Test the configuration** - -:: - - sudo nginx -s reload - -* Open your browser and clear your cache. -* Logon to your Nextcloud instance, open the gallery app, move through your - folders and watch while the thumbnails are generated for the first time. -* You may also watch with eg. ``htop`` your system load while the - thumbnails are processed. -* Go to 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. From dc676ca45e1a2d209ac37ca8fd3f5514b825f681 Mon Sep 17 00:00:00 2001 From: Morris Jobke Date: Sun, 14 May 2017 13:29:55 -0500 Subject: [PATCH 2/2] Combine nginx_example and nginx into one page Signed-off-by: Morris Jobke --- .../security_setup_warnings.rst | 2 +- admin_manual/installation/index.rst | 1 - admin_manual/installation/nginx.rst | 69 +++++++++++++++-- admin_manual/installation/nginx_examples.rst | 75 ------------------- .../installation/source_installation.rst | 2 +- .../issues/general_troubleshooting.rst | 4 +- admin_manual/release_notes.rst | 3 + 7 files changed, 68 insertions(+), 88 deletions(-) delete mode 100644 admin_manual/installation/nginx_examples.rst diff --git a/admin_manual/configuration_server/security_setup_warnings.rst b/admin_manual/configuration_server/security_setup_warnings.rst index 51bd96989..e74f077f6 100644 --- a/admin_manual/configuration_server/security_setup_warnings.rst +++ b/admin_manual/configuration_server/security_setup_warnings.rst @@ -59,7 +59,7 @@ describe how to enable HTTPS on the Apache and Nginx Web servers. :ref:`use_https_label` -:doc:`../installation/nginx_examples` +:doc:`../installation/nginx` The test with getenv(\"PATH\") only returns an empty response ------------------------------------------------------------- diff --git a/admin_manual/installation/index.rst b/admin_manual/installation/index.rst index c51bb8947..474549676 100644 --- a/admin_manual/installation/index.rst +++ b/admin_manual/installation/index.rst @@ -13,5 +13,4 @@ Installation apps_management_installation apps_supported selinux_configuration - nginx_examples nginx diff --git a/admin_manual/installation/nginx.rst b/admin_manual/installation/nginx.rst index f313bd75b..00c7caafa 100644 --- a/admin_manual/installation/nginx.rst +++ b/admin_manual/installation/nginx.rst @@ -2,12 +2,25 @@ Nginx Configuration =================== -The following configuration should be used when Nextcloud is placed in the -webroot of your Nginx installation. Be careful about line breaks if you copy -the examples, as long lines may be broken for page formatting. +This page covers example Nginx configurations to use with running an Nextcloud +server. This page is community-maintained. (Thank you, contributors!) -Some environments might need a ``cgi.fix_pathinfo`` set to ``1`` in their -``php.ini``. +- You need to insert the following code into **your Nginx configuration file.** +- Adjust **server_name**, **root**, **ssl_certificate** and + **ssl_certificate_key** to suit your needs. +- Make sure your SSL certificates are readable by the server (see `nginx HTTP + SSL Module documentation `_). +- ``add_header`` statements are only taken from the current level and are not + cascaded from or to a different level. All necessary ``add_header`` + statements must be defined in each level needed. For better readability it + is possible to move *common* add header statements into a separate file + and include that file wherever necessary. However, each ``add_header`` + statement must be written in a single line to prevent connection problems + with sync clients. +- Be careful about line breaks if you copy the examples, as long lines may be + broken for page formatting. +- Some environments might need a ``cgi.fix_pathinfo`` set to ``1`` in their + ``php.ini``. Thanks to `@josh4trunks `_ for providing / creating these configuration examples. @@ -15,8 +28,9 @@ creating these configuration examples. Nextcloud in the webroot of nginx --------------------------------- -The following config should be used when Nextcloud is placed in the webroot of -your nginx installation. +The following configuration should be used when Nextcloud is placed in the +webroot of your nginx installation. In this example it is +``/var/www/nextcloud`` and it is accessed via ``http(s)://cloud.example.com`` .. code-block:: nginx @@ -273,4 +287,43 @@ your nginx installation. } } } - + +Tips and Tricks +--------------- + +Suppressing Log Messages +======================== + +If you're seeing meaningless messages in your logfile, for example ``client +denied by server configuration: /var/www/data/htaccesstest.txt``, add this section to +your nginx configuration to suppress them: + +.. code-block:: nginx + + location = /data/htaccesstest.txt { + allow all; + log_not_found off; + access_log off; + } + +JavaScript (.js) or CSS (.css) files not served properly +======================================================== + +A common issue with custom nginx configs is that JavaScript (.js) +or CSS (.css) files are not served properly leading to a 404 (File not found) +error on those files and a broken webinterface. + +This could be caused by the: + +.. code-block:: nginx + + location ~* \.(?:css|js)$ { + +block shown above not located **below** the: + +.. code-block:: nginx + + location ~ \.php(?:$|/) { + +block. Other custom configurations like caching JavaScript (.js) +or CSS (.css) files via gzip could also cause such issues. diff --git a/admin_manual/installation/nginx_examples.rst b/admin_manual/installation/nginx_examples.rst deleted file mode 100644 index d5974d088..000000000 --- a/admin_manual/installation/nginx_examples.rst +++ /dev/null @@ -1,75 +0,0 @@ -============================ -Nginx Example Configurations -============================ - -This page covers example Nginx configurations to use with running an Nextcloud -server. This page is community-maintained. (Thank you, contributors!) - - -- You need to insert the following code into **your Nginx configuration file.** -- The configuration assumes that Nextcloud is installed in - ``/var/www/nextcloud`` and that it is accessed via - ``http(s)://cloud.example.com``. -- Adjust **server_name**, **root**, **ssl_certificate** and - **ssl_certificate_key** to suit your needs. -- Make sure your SSL certificates are readable by the server (see `nginx HTTP - SSL Module documentation `_). -- ``add_header`` statements are only taken from the current level and are not - cascaded from or to a different level. All necessary ``add_header`` - statements must be defined in each level needed. For better readability it - is possible to move *common* add header statements into a separate file - and include that file wherever necessary. However, each ``add_header`` - statement must be written in a single line to prevent connection problems - with sync clients. - -Example Configurations ----------------------- - -- :doc:`nginx` - -You can use Nextcloud over plain http, but we strongly encourage you to use -SSL/TLS to encrypt all of your server traffic, and to protect user's logins and -data in transit. - -- Remove the server block containing the redirect -- Change **listen 443 ssl** to **listen 80;** -- Remove **ssl_certificate** and **ssl_certificate_key**. -- Remove **fastcgi_params HTTPS on;** - -Suppressing Log Messages -======================== - -If you're seeing meaningless messages in your logfile, for example `client -denied by server configuration: /var/www/data/htaccesstest.txt -`_, add this section to -your nginx configuration to suppress them: - -.. code-block:: nginx - - location = /data/htaccesstest.txt { - allow all; - log_not_found off; - access_log off; - } - -JavaScript (.js) or CSS (.css) files not served properly -======================================================== - -A common issue with custom nginx configs is that JavaScript (.js) -or CSS (.css) files are not served properly leading to a 404 (File not found) -error on those files and a broken webinterface. - -This could be caused by the: - -.. code-block:: nginx - - location ~* \.(?:css|js)$ { - -block shown above not located **below** the: - -.. code-block:: nginx - - location ~ \.php(?:$|/) { - -block. Other custom configurations like caching JavaScript (.js) -or CSS (.css) files via gzip could also cause such issues. diff --git a/admin_manual/installation/source_installation.rst b/admin_manual/installation/source_installation.rst index bda3aeb6a..09d364bf2 100644 --- a/admin_manual/installation/source_installation.rst +++ b/admin_manual/installation/source_installation.rst @@ -454,7 +454,7 @@ be set in the ``nextcloud/.user.ini`` file. Other Web Servers ----------------- -:doc:`nginx_examples` +:doc:`nginx` `Other HTTP servers (Nextcloud) diff --git a/admin_manual/issues/general_troubleshooting.rst b/admin_manual/issues/general_troubleshooting.rst index dedf2c51e..9cda03cb0 100644 --- a/admin_manual/issues/general_troubleshooting.rst +++ b/admin_manual/issues/general_troubleshooting.rst @@ -261,8 +261,8 @@ and if running in a subfolder like ``nextcloud``: For the first case the :file:`.htaccess` file shipped with Nextcloud should do this work for your when running Apache. You only need to make sure that your -Web server is using this file. When running NGINX please refer to -:doc:`../installation/nginx_examples`. +Web server is using this file. When running Nginx please refer to +:doc:`../installation/nginx. If your Nextcloud instance is installed in a subfolder called ``nextcloud`` and diff --git a/admin_manual/release_notes.rst b/admin_manual/release_notes.rst index 7e02afe8e..309ffc90a 100644 --- a/admin_manual/release_notes.rst +++ b/admin_manual/release_notes.rst @@ -15,6 +15,9 @@ Updates to Nginx configuration those lines in your Nginx config: ``add_header X-Frame-Options "SAMEORIGIN";`` See :doc:`installation/nginx` +* For improvements in serving HTTP requests the Nginx configuration now has + HTTP 2 enabled. Please update your Nginx config accordingly. See + :doc:`installation/nginx` Q & A -----