From 035af33a75685f21e785818ff3c447de71c6417d Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Mon, 15 Nov 2021 12:10:41 +0100 Subject: [PATCH 1/3] modernize the web server configuration chapter --- setup/web_server_configuration.rst | 355 +++++++---------------------- 1 file changed, 82 insertions(+), 273 deletions(-) diff --git a/setup/web_server_configuration.rst b/setup/web_server_configuration.rst index f5f259413b5..7090572379a 100644 --- a/setup/web_server_configuration.rst +++ b/setup/web_server_configuration.rst @@ -5,17 +5,12 @@ The preferred way to develop your Symfony application is to use :doc:`Symfony Local Web Server `. However, when running the application in the production environment, you'll need -to use a fully-featured web server. This article describes several ways to use -Symfony with Apache or Nginx. +to use a fully-featured web server. This article describes how to use Symfony +with Apache or Nginx. -When using Apache, you can configure PHP as an -:ref:`Apache module ` or with FastCGI using -:ref:`PHP FPM `. FastCGI also is the preferred way -to use PHP :ref:`with Nginx `. +.. sidebar:: The public directory -.. sidebar:: The ``public/`` directory - - The ``public/`` directory is the home of all of your application's public and + The public directory is the home of all of your application's public and static files, including images, stylesheets and JavaScript files. It is also where the front controller (``index.php``) lives. @@ -27,7 +22,83 @@ to use PHP :ref:`with Nginx `. another location (e.g. ``public_html/``) make sure you :ref:`override the location of the public/ directory `. -.. _web-server-nginx: +Apache with PHP-FPM +------------------- + +To make use of PHP-FPM with Apache, you first have to ensure that you have +the FastCGI process manager ``php-fpm`` binary and Apache's FastCGI module +installed (for example, on a Debian based system you have to install the +``libapache2-mod-fastcgi`` and ``php7.4-fpm`` packages). + +PHP-FPM uses so-called *pools* to handle incoming FastCGI requests. You can +configure an arbitrary number of pools in the FPM configuration. In a pool +you configure either a TCP socket (IP and port) or a Unix domain socket to +listen on. Each pool can also be run under a different UID and GID: + +.. code-block:: ini + + ; a pool called www + [www] + user = www-data + group = www-data + + ; use a unix domain socket + listen = /var/run/php/php7.4-fpm.sock + + ; or listen on a TCP socket + listen = 127.0.0.1:9000 + +Using mod_proxy_fcgi with Apache 2.4 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are running Apache 2.4, you can use ``mod_proxy_fcgi`` to pass incoming +requests to PHP-FPM. Configure PHP-FPM to listen on a TCP or Unix socket, enable +``mod_proxy`` and ``mod_proxy_fcgi`` in your Apache configuration, and use the +``SetHandler`` directive to pass requests for PHP files to PHP FPM: + +.. code-block:: apache + + + ServerName domain.tld + ServerAlias www.domain.tld + + # Uncomment the following line to force Apache to pass the Authorization + # header to PHP: required for "basic_auth" under PHP-FPM and FastCGI + # + # SetEnvIfNoCase ^Authorization$ "(.+)" HTTP_AUTHORIZATION=$1 + + # For Apache 2.4.9 or higher + # Using SetHandler avoids issues with using ProxyPassMatch in combination + # with mod_rewrite or mod_autoindex + + SetHandler proxy:fcgi://127.0.0.1:9000 + # for Unix sockets, Apache 2.4.10 or higher + # SetHandler proxy:unix:/path/to/fpm.sock|fcgi://dummy + + + # If you use Apache version below 2.4.9 you must consider update or use this instead + # ProxyPassMatch ^/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/public/$1 + + # If you run your Symfony application on a subpath of your document root, the + # regular expression must be changed accordingly: + # ProxyPassMatch ^/path-to-app/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/public/$1 + + DocumentRoot /var/www/project/public + + AllowOverride None + Require all granted + FallbackResource /index.php + + + # uncomment the following lines if you install assets as symlinks + # or run into problems when compiling LESS/Sass/CoffeeScript assets + # + # Options FollowSymlinks + # + + ErrorLog /var/log/apache2/project_error.log + CustomLog /var/log/apache2/project_access.log combined + Nginx ----- @@ -53,7 +124,7 @@ The **minimum configuration** to get your application running under Nginx is: # } location ~ ^/index\.php(/|$) { - fastcgi_pass unix:/var/run/php/php-fpm.sock; + fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; fastcgi_split_path_info ^(.+\.php)(/.*)$; include fastcgi_params; @@ -115,268 +186,6 @@ The **minimum configuration** to get your application running under Nginx is: For advanced Nginx configuration options, read the official `Nginx documentation`_. -.. _web-server-apache-mod-php: - -Adding Rewrite Rules for Apache -------------------------------- - -The easiest way is to install the ``apache`` :ref:`Symfony pack ` -by executing the following command: - -.. code-block:: terminal - - $ composer require symfony/apache-pack - -This pack installs a ``.htaccess`` file in the ``public/`` directory that contains -the rewrite rules needed to serve the Symfony application. - -In production servers, you should move the ``.htaccess`` rules into the main -Apache configuration file to improve performance. To do so, copy the -``.htaccess`` contents inside the ```` configuration associated to -the Symfony application ``public/`` directory (and replace ``AllowOverride All`` -by ``AllowOverride None``): - -.. code-block:: apache - - - # ... - DocumentRoot /var/www/project/public - - - AllowOverride None - - # Copy .htaccess contents here - - - -Apache with mod_php/PHP-CGI ---------------------------- - -The **minimum configuration** to get your application running under Apache is: - -.. code-block:: apache - - - ServerName domain.tld - ServerAlias www.domain.tld - - DocumentRoot /var/www/project/public - - AllowOverride All - Order Allow,Deny - Allow from All - - - # uncomment the following lines if you install assets as symlinks - # or run into problems when compiling LESS/Sass/CoffeeScript assets - # - # Options FollowSymlinks - # - - ErrorLog /var/log/apache2/project_error.log - CustomLog /var/log/apache2/project_access.log combined - - -.. tip:: - - If your system supports the ``APACHE_LOG_DIR`` variable, you may want - to use ``${APACHE_LOG_DIR}/`` instead of hardcoding ``/var/log/apache2/``. - -Use the following **optimized configuration** to disable ``.htaccess`` support -and increase web server performance: - -.. code-block:: apache - - - ServerName domain.tld - ServerAlias www.domain.tld - - DocumentRoot /var/www/project/public - DirectoryIndex /index.php - - - AllowOverride None - Order Allow,Deny - Allow from All - - FallbackResource /index.php - - - # uncomment the following lines if you install assets as symlinks - # or run into problems when compiling LESS/Sass/CoffeeScript assets - # - # Options FollowSymlinks - # - - # optionally disable the fallback resource for the asset directories - # which will allow Apache to return a 404 error when files are - # not found instead of passing the request to Symfony - - DirectoryIndex disabled - FallbackResource disabled - - ErrorLog /var/log/apache2/project_error.log - CustomLog /var/log/apache2/project_access.log combined - - # optionally set the value of the environment variables used in the application - #SetEnv APP_ENV prod - #SetEnv APP_SECRET - #SetEnv DATABASE_URL "mysql://db_user:db_pass@host:3306/db_name" - - -.. caution:: - - Use ``FallbackResource`` on Apache 2.4.25 or higher, due to a bug which was - fixed on that release causing the root ``/`` to hang. - -.. tip:: - - If you are using **php-cgi**, Apache does not pass HTTP basic username and - password to PHP by default. To work around this limitation, you should use - the following configuration snippet: - - .. code-block:: apache - - RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}] - -Using mod_php/PHP-CGI with Apache 2.4 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In Apache 2.4, ``Order Allow,Deny`` has been replaced by ``Require all granted``. -Hence, you need to modify your ``Directory`` permission settings as follows: - -.. code-block:: apache - - - Require all granted - # ... - - -For advanced Apache configuration options, read the official `Apache documentation`_. - -.. _web-server-apache-fpm: - -Apache with PHP-FPM -------------------- - -To make use of PHP-FPM with Apache, you first have to ensure that you have -the FastCGI process manager ``php-fpm`` binary and Apache's FastCGI module -installed (for example, on a Debian based system you have to install the -``libapache2-mod-fastcgi`` and ``php-fpm`` packages). - -PHP-FPM uses so-called *pools* to handle incoming FastCGI requests. You can -configure an arbitrary number of pools in the FPM configuration. In a pool -you configure either a TCP socket (IP and port) or a Unix domain socket to -listen on. Each pool can also be run under a different UID and GID: - -.. code-block:: ini - - ; a pool called www - [www] - user = www-data - group = www-data - - ; use a unix domain socket - listen = /var/run/php/php-fpm.sock - - ; or listen on a TCP socket - listen = 127.0.0.1:9000 - -Using mod_proxy_fcgi with Apache 2.4 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you are running Apache 2.4, you can use ``mod_proxy_fcgi`` to pass incoming -requests to PHP-FPM. Configure PHP-FPM to listen on a TCP or Unix socket, enable -``mod_proxy`` and ``mod_proxy_fcgi`` in your Apache configuration, and use the -``SetHandler`` directive to pass requests for PHP files to PHP FPM: - -.. code-block:: apache - - - ServerName domain.tld - ServerAlias www.domain.tld - - # Uncomment the following line to force Apache to pass the Authorization - # header to PHP: required for "basic_auth" under PHP-FPM and FastCGI - # - # SetEnvIfNoCase ^Authorization$ "(.+)" HTTP_AUTHORIZATION=$1 - - # For Apache 2.4.9 or higher - # Using SetHandler avoids issues with using ProxyPassMatch in combination - # with mod_rewrite or mod_autoindex - - SetHandler proxy:fcgi://127.0.0.1:9000 - # for Unix sockets, Apache 2.4.10 or higher - # SetHandler proxy:unix:/path/to/fpm.sock|fcgi://dummy - - - # If you use Apache version below 2.4.9 you must consider update or use this instead - # ProxyPassMatch ^/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/public/$1 - - # If you run your Symfony application on a subpath of your document root, the - # regular expression must be changed accordingly: - # ProxyPassMatch ^/path-to-app/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/public/$1 - - DocumentRoot /var/www/project/public - - # enable the .htaccess rewrites - AllowOverride All - Require all granted - - - # uncomment the following lines if you install assets as symlinks - # or run into problems when compiling LESS/Sass/CoffeeScript assets - # - # Options FollowSymlinks - # - - ErrorLog /var/log/apache2/project_error.log - CustomLog /var/log/apache2/project_access.log combined - - -PHP-FPM with Apache 2.2 -~~~~~~~~~~~~~~~~~~~~~~~ - -On Apache 2.2 or lower, you cannot use ``mod_proxy_fcgi``. You have to use -the `FastCgiExternalServer`_ directive instead. Therefore, your Apache configuration -should look something like this: - -.. code-block:: apache - - - ServerName domain.tld - ServerAlias www.domain.tld - - AddHandler php7-fcgi .php - Action php7-fcgi /php7-fcgi - Alias /php7-fcgi /usr/lib/cgi-bin/php7-fcgi - FastCgiExternalServer /usr/lib/cgi-bin/php7-fcgi -host 127.0.0.1:9000 -pass-header Authorization - - DocumentRoot /var/www/project/public - - # enable the .htaccess rewrites - AllowOverride All - Order Allow,Deny - Allow from all - - - # uncomment the following lines if you install assets as symlinks - # or run into problems when compiling LESS/Sass/CoffeeScript assets - # - # Options FollowSymlinks - # - - ErrorLog /var/log/apache2/project_error.log - CustomLog /var/log/apache2/project_access.log combined - - -If you prefer to use a Unix socket, you have to use the ``-socket`` option -instead: - -.. code-block:: apache - - FastCgiExternalServer /usr/lib/cgi-bin/php7-fcgi -socket /var/run/php/php-fpm.sock -pass-header Authorization - .. _`Apache documentation`: https://httpd.apache.org/docs/ .. _`FastCgiExternalServer`: https://docs.oracle.com/cd/B31017_01/web.1013/q20204/mod_fastcgi.html#FastCgiExternalServer .. _`Nginx documentation`: https://www.nginx.com/resources/wiki/start/topics/recipes/symfony/ From 33ea1fa13bd986c5021b8dbada9cb1af3ea1211b Mon Sep 17 00:00:00 2001 From: Wouter de Jong Date: Tue, 20 Dec 2022 22:55:59 +0100 Subject: [PATCH 2/3] Clean-up Apache and Nginx parts --- setup/web_server_configuration.rst | 109 +++++++++++++++++++---------- 1 file changed, 72 insertions(+), 37 deletions(-) diff --git a/setup/web_server_configuration.rst b/setup/web_server_configuration.rst index 7090572379a..1682c8a58de 100644 --- a/setup/web_server_configuration.rst +++ b/setup/web_server_configuration.rst @@ -22,13 +22,12 @@ with Apache or Nginx. another location (e.g. ``public_html/``) make sure you :ref:`override the location of the public/ directory `. -Apache with PHP-FPM +Configuring PHP-FPM ------------------- -To make use of PHP-FPM with Apache, you first have to ensure that you have -the FastCGI process manager ``php-fpm`` binary and Apache's FastCGI module -installed (for example, on a Debian based system you have to install the -``libapache2-mod-fastcgi`` and ``php7.4-fpm`` packages). +All configuration examples below use the PHP FastCGI process manager +(PHP-FPM). Ensure that you have installed PHP-FPM (for example, on a Debian +based system you have to install the ``php-fpm`` package). PHP-FPM uses so-called *pools* to handle incoming FastCGI requests. You can configure an arbitrary number of pools in the FPM configuration. In a pool @@ -37,6 +36,8 @@ listen on. Each pool can also be run under a different UID and GID: .. code-block:: ini + ; /etc/php/7.4/fpm/pool.d/www.conf + ; a pool called www [www] user = www-data @@ -45,43 +46,37 @@ listen on. Each pool can also be run under a different UID and GID: ; use a unix domain socket listen = /var/run/php/php7.4-fpm.sock - ; or listen on a TCP socket - listen = 127.0.0.1:9000 + ; or listen on a TCP connection + ; listen = 127.0.0.1:9000 -Using mod_proxy_fcgi with Apache 2.4 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Apache +------ -If you are running Apache 2.4, you can use ``mod_proxy_fcgi`` to pass incoming -requests to PHP-FPM. Configure PHP-FPM to listen on a TCP or Unix socket, enable -``mod_proxy`` and ``mod_proxy_fcgi`` in your Apache configuration, and use the -``SetHandler`` directive to pass requests for PHP files to PHP FPM: +If you are running Apache 2.4+, you can use ``mod_proxy_fcgi`` to pass +incoming requests to PHP-FPM. Install the Apache2 FastCGI mod +(``libapache2-mod-fastcgi`` on Debian), enable ``mod_proxy`` and +``mod_proxy_fcgi`` in your Apache configuration, and use the ``SetHandler`` +directive to pass requests for PHP files to PHP FPM: .. code-block:: apache + # /etc/apache2/conf.d/example.com.conf - ServerName domain.tld - ServerAlias www.domain.tld + ServerName example.com + ServerAlias www.example.com # Uncomment the following line to force Apache to pass the Authorization # header to PHP: required for "basic_auth" under PHP-FPM and FastCGI # # SetEnvIfNoCase ^Authorization$ "(.+)" HTTP_AUTHORIZATION=$1 - # For Apache 2.4.9 or higher - # Using SetHandler avoids issues with using ProxyPassMatch in combination - # with mod_rewrite or mod_autoindex - SetHandler proxy:fcgi://127.0.0.1:9000 - # for Unix sockets, Apache 2.4.10 or higher - # SetHandler proxy:unix:/path/to/fpm.sock|fcgi://dummy - - - # If you use Apache version below 2.4.9 you must consider update or use this instead - # ProxyPassMatch ^/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/public/$1 + # when using PHP-FPM as a unix socket + SetHandler proxy:unix:/var/run/php/php7.4-fpm.sock|fcgi://dummy - # If you run your Symfony application on a subpath of your document root, the - # regular expression must be changed accordingly: - # ProxyPassMatch ^/path-to-app/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/public/$1 + # when PHP-FPM is configured to use TCP + # SetHandler proxy:fcgi://127.0.0.1:9000 + DocumentRoot /var/www/project/public @@ -107,8 +102,9 @@ The **minimum configuration** to get your application running under Nginx is: .. code-block:: nginx + # /etc/nginx/conf.d/example.com.conf server { - server_name domain.tld www.domain.tld; + server_name example.com www.example.com; root /var/www/project/public; location / { @@ -124,7 +120,12 @@ The **minimum configuration** to get your application running under Nginx is: # } location ~ ^/index\.php(/|$) { + # when using PHP-FPM as a unix socket fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; + + # when PHP-FPM is configured to use TCP + # fastcgi_pass 127.0.0.1:9000; + fastcgi_split_path_info ^(.+\.php)(/.*)$; include fastcgi_params; @@ -146,7 +147,7 @@ The **minimum configuration** to get your application running under Nginx is: fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; fastcgi_param DOCUMENT_ROOT $realpath_root; # Prevents URIs that include the front controller. This will 404: - # http://domain.tld/index.php/some-path + # http://example.com/index.php/some-path # Remove the internal directive to allow URIs like this internal; } @@ -166,11 +167,6 @@ The **minimum configuration** to get your application running under Nginx is: If you use NGINX Unit, check out the official article about `How to run Symfony applications using NGINX Unit`_. -.. note:: - - Depending on your PHP-FPM config, the ``fastcgi_pass`` can also be - ``fastcgi_pass 127.0.0.1:9000``. - .. tip:: This executes **only** ``index.php`` in the public directory. All other files @@ -186,7 +182,46 @@ The **minimum configuration** to get your application running under Nginx is: For advanced Nginx configuration options, read the official `Nginx documentation`_. -.. _`Apache documentation`: https://httpd.apache.org/docs/ -.. _`FastCgiExternalServer`: https://docs.oracle.com/cd/B31017_01/web.1013/q20204/mod_fastcgi.html#FastCgiExternalServer +Caddy +----- + +When using Caddy on the server, you can use a configuration like this: + +.. code-block:: raw + + # /etc/caddy/Caddyfile + example.com, www.example.com { + root * /var/www/project/public + + # serve files directly if they can be found (e.g. CSS or JS files in public/) + encode zstd gzip + file_server + + + # otherwise, use PHP-FPM (replace "unix//var/..." with "127.0.0.1:9000" when using TCP) + php_fastcgi unix//var/run/php/php7.4-fpm.sock { + # optionally set the value of the environment variables used in the application + # env APP_ENV "prod" + # env APP_SECRET "" + # env DATABASE_URL "mysql://db_user:db_pass@host:3306/db_name" + + # Configure the FastCGI to resolve any symlinks in the root path. + # This ensures that OpCache is using the destination filenames, + # instead of the symlinks, to cache opcodes and php files see + # https://caddy.community/t/root-symlink-folder-updates-and-caddy-reload-not-working/10557 + resolve_root_symlink + } + + # return 404 for all other php files not matching the front controller + # this prevents access to other php files you don't want to be accessible. + @phpFile { + path *.php* + } + error @phpFile "Not found" 404 + } + +See the `official Caddy documentation`_ for more examples, such as using +Caddy in a container infrastructure. + .. _`Nginx documentation`: https://www.nginx.com/resources/wiki/start/topics/recipes/symfony/ .. _`How to run Symfony applications using NGINX Unit`: https://unit.nginx.org/howto/symfony/ From 679bf644642007fb17c40f5748d304666d4aa321 Mon Sep 17 00:00:00 2001 From: Wouter de Jong Date: Tue, 20 Dec 2022 22:56:05 +0100 Subject: [PATCH 3/3] Add Caddy section --- setup/web_server_configuration.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/setup/web_server_configuration.rst b/setup/web_server_configuration.rst index 1682c8a58de..6723d0abaa3 100644 --- a/setup/web_server_configuration.rst +++ b/setup/web_server_configuration.rst @@ -6,7 +6,7 @@ The preferred way to develop your Symfony application is to use However, when running the application in the production environment, you'll need to use a fully-featured web server. This article describes how to use Symfony -with Apache or Nginx. +with Apache, Nginx or Caddy. .. sidebar:: The public directory @@ -187,7 +187,7 @@ Caddy When using Caddy on the server, you can use a configuration like this: -.. code-block:: raw +.. code-block:: text # /etc/caddy/Caddyfile example.com, www.example.com { @@ -225,3 +225,4 @@ Caddy in a container infrastructure. .. _`Nginx documentation`: https://www.nginx.com/resources/wiki/start/topics/recipes/symfony/ .. _`How to run Symfony applications using NGINX Unit`: https://unit.nginx.org/howto/symfony/ +.. _`official Caddy documentation`: https://caddyserver.com/docs/