Skip to content

Commit 035af33

Browse files
xabbuhwouterj
xabbuh
authored and
wouterj
committed
modernize the web server configuration chapter
1 parent 7f314f5 commit 035af33

File tree

1 file changed

+82
-273
lines changed

1 file changed

+82
-273
lines changed

‎setup/web_server_configuration.rst‎

Lines changed: 82 additions & 273 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,12 @@ The preferred way to develop your Symfony application is to use
55
:doc:`Symfony Local Web Server </setup/symfony_server>`.
66

77
However, when running the application in the production environment, you'll need
8-
to use a fully-featured web server. This article describes several ways to use
9-
Symfony with Apache or Nginx.
8+
to use a fully-featured web server. This article describes how to use Symfony
9+
with Apache or Nginx.
1010

11-
When using Apache, you can configure PHP as an
12-
:ref:`Apache module <web-server-apache-mod-php>` or with FastCGI using
13-
:ref:`PHP FPM <web-server-apache-fpm>`. FastCGI also is the preferred way
14-
to use PHP :ref:`with Nginx <web-server-nginx>`.
11+
.. sidebar:: The public directory
1512

16-
.. sidebar:: The ``public/`` directory
17-
18-
The ``public/`` directory is the home of all of your application's public and
13+
The public directory is the home of all of your application's public and
1914
static files, including images, stylesheets and JavaScript files. It is
2015
also where the front controller (``index.php``) lives.
2116

@@ -27,7 +22,83 @@ to use PHP :ref:`with Nginx <web-server-nginx>`.
2722
another location (e.g. ``public_html/``) make sure you
2823
:ref:`override the location of the public/ directory <override-web-dir>`.
2924

30-
.. _web-server-nginx:
25+
Apache with PHP-FPM
26+
-------------------
27+
28+
To make use of PHP-FPM with Apache, you first have to ensure that you have
29+
the FastCGI process manager ``php-fpm`` binary and Apache's FastCGI module
30+
installed (for example, on a Debian based system you have to install the
31+
``libapache2-mod-fastcgi`` and ``php7.4-fpm`` packages).
32+
33+
PHP-FPM uses so-called *pools* to handle incoming FastCGI requests. You can
34+
configure an arbitrary number of pools in the FPM configuration. In a pool
35+
you configure either a TCP socket (IP and port) or a Unix domain socket to
36+
listen on. Each pool can also be run under a different UID and GID:
37+
38+
.. code-block:: ini
39+
40+
; a pool called www
41+
[www]
42+
user = www-data
43+
group = www-data
44+
45+
; use a unix domain socket
46+
listen = /var/run/php/php7.4-fpm.sock
47+
48+
; or listen on a TCP socket
49+
listen = 127.0.0.1:9000
50+
51+
Using mod_proxy_fcgi with Apache 2.4
52+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
53+
54+
If you are running Apache 2.4, you can use ``mod_proxy_fcgi`` to pass incoming
55+
requests to PHP-FPM. Configure PHP-FPM to listen on a TCP or Unix socket, enable
56+
``mod_proxy`` and ``mod_proxy_fcgi`` in your Apache configuration, and use the
57+
``SetHandler`` directive to pass requests for PHP files to PHP FPM:
58+
59+
.. code-block:: apache
60+
61+
<VirtualHost *:80>
62+
ServerName domain.tld
63+
ServerAlias www.domain.tld
64+
65+
# Uncomment the following line to force Apache to pass the Authorization
66+
# header to PHP: required for "basic_auth" under PHP-FPM and FastCGI
67+
#
68+
# SetEnvIfNoCase ^Authorization$ "(.+)" HTTP_AUTHORIZATION=$1
69+
70+
# For Apache 2.4.9 or higher
71+
# Using SetHandler avoids issues with using ProxyPassMatch in combination
72+
# with mod_rewrite or mod_autoindex
73+
<FilesMatch \.php$>
74+
SetHandler proxy:fcgi://127.0.0.1:9000
75+
# for Unix sockets, Apache 2.4.10 or higher
76+
# SetHandler proxy:unix:/path/to/fpm.sock|fcgi://dummy
77+
</FilesMatch>
78+
79+
# If you use Apache version below 2.4.9 you must consider update or use this instead
80+
# ProxyPassMatch ^/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/public/$1
81+
82+
# If you run your Symfony application on a subpath of your document root, the
83+
# regular expression must be changed accordingly:
84+
# ProxyPassMatch ^/path-to-app/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/public/$1
85+
86+
DocumentRoot /var/www/project/public
87+
<Directory /var/www/project/public>
88+
AllowOverride None
89+
Require all granted
90+
FallbackResource /index.php
91+
</Directory>
92+
93+
# uncomment the following lines if you install assets as symlinks
94+
# or run into problems when compiling LESS/Sass/CoffeeScript assets
95+
# <Directory /var/www/project>
96+
# Options FollowSymlinks
97+
# </Directory>
98+
99+
ErrorLog /var/log/apache2/project_error.log
100+
CustomLog /var/log/apache2/project_access.log combined
101+
</VirtualHost>
31102
32103
Nginx
33104
-----
@@ -53,7 +124,7 @@ The **minimum configuration** to get your application running under Nginx is:
53124
# }
54125
55126
location ~ ^/index\.php(/|$) {
56-
fastcgi_pass unix:/var/run/php/php-fpm.sock;
127+
fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
57128
fastcgi_split_path_info ^(.+\.php)(/.*)$;
58129
include fastcgi_params;
59130
@@ -115,268 +186,6 @@ The **minimum configuration** to get your application running under Nginx is:
115186

116187
For advanced Nginx configuration options, read the official `Nginx documentation`_.
117188

118-
.. _web-server-apache-mod-php:
119-
120-
Adding Rewrite Rules for Apache
121-
-------------------------------
122-
123-
The easiest way is to install the ``apache`` :ref:`Symfony pack <symfony-packs>`
124-
by executing the following command:
125-
126-
.. code-block:: terminal
127-
128-
$ composer require symfony/apache-pack
129-
130-
This pack installs a ``.htaccess`` file in the ``public/`` directory that contains
131-
the rewrite rules needed to serve the Symfony application.
132-
133-
In production servers, you should move the ``.htaccess`` rules into the main
134-
Apache configuration file to improve performance. To do so, copy the
135-
``.htaccess`` contents inside the ``<Directory>`` configuration associated to
136-
the Symfony application ``public/`` directory (and replace ``AllowOverride All``
137-
by ``AllowOverride None``):
138-
139-
.. code-block:: apache
140-
141-
<VirtualHost *:80>
142-
# ...
143-
DocumentRoot /var/www/project/public
144-
145-
<Directory /var/www/project/public>
146-
AllowOverride None
147-
148-
# Copy .htaccess contents here
149-
</Directory>
150-
</VirtualHost>
151-
152-
Apache with mod_php/PHP-CGI
153-
---------------------------
154-
155-
The **minimum configuration** to get your application running under Apache is:
156-
157-
.. code-block:: apache
158-
159-
<VirtualHost *:80>
160-
ServerName domain.tld
161-
ServerAlias www.domain.tld
162-
163-
DocumentRoot /var/www/project/public
164-
<Directory /var/www/project/public>
165-
AllowOverride All
166-
Order Allow,Deny
167-
Allow from All
168-
</Directory>
169-
170-
# uncomment the following lines if you install assets as symlinks
171-
# or run into problems when compiling LESS/Sass/CoffeeScript assets
172-
# <Directory /var/www/project>
173-
# Options FollowSymlinks
174-
# </Directory>
175-
176-
ErrorLog /var/log/apache2/project_error.log
177-
CustomLog /var/log/apache2/project_access.log combined
178-
</VirtualHost>
179-
180-
.. tip::
181-
182-
If your system supports the ``APACHE_LOG_DIR`` variable, you may want
183-
to use ``${APACHE_LOG_DIR}/`` instead of hardcoding ``/var/log/apache2/``.
184-
185-
Use the following **optimized configuration** to disable ``.htaccess`` support
186-
and increase web server performance:
187-
188-
.. code-block:: apache
189-
190-
<VirtualHost *:80>
191-
ServerName domain.tld
192-
ServerAlias www.domain.tld
193-
194-
DocumentRoot /var/www/project/public
195-
DirectoryIndex /index.php
196-
197-
<Directory /var/www/project/public>
198-
AllowOverride None
199-
Order Allow,Deny
200-
Allow from All
201-
202-
FallbackResource /index.php
203-
</Directory>
204-
205-
# uncomment the following lines if you install assets as symlinks
206-
# or run into problems when compiling LESS/Sass/CoffeeScript assets
207-
# <Directory /var/www/project>
208-
# Options FollowSymlinks
209-
# </Directory>
210-
211-
# optionally disable the fallback resource for the asset directories
212-
# which will allow Apache to return a 404 error when files are
213-
# not found instead of passing the request to Symfony
214-
<Directory /var/www/project/public/bundles>
215-
DirectoryIndex disabled
216-
FallbackResource disabled
217-
</Directory>
218-
ErrorLog /var/log/apache2/project_error.log
219-
CustomLog /var/log/apache2/project_access.log combined
220-
221-
# optionally set the value of the environment variables used in the application
222-
#SetEnv APP_ENV prod
223-
#SetEnv APP_SECRET <app-secret-id>
224-
#SetEnv DATABASE_URL "mysql://db_user:db_pass@host:3306/db_name"
225-
</VirtualHost>
226-
227-
.. caution::
228-
229-
Use ``FallbackResource`` on Apache 2.4.25 or higher, due to a bug which was
230-
fixed on that release causing the root ``/`` to hang.
231-
232-
.. tip::
233-
234-
If you are using **php-cgi**, Apache does not pass HTTP basic username and
235-
password to PHP by default. To work around this limitation, you should use
236-
the following configuration snippet:
237-
238-
.. code-block:: apache
239-
240-
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
241-
242-
Using mod_php/PHP-CGI with Apache 2.4
243-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
244-
245-
In Apache 2.4, ``Order Allow,Deny`` has been replaced by ``Require all granted``.
246-
Hence, you need to modify your ``Directory`` permission settings as follows:
247-
248-
.. code-block:: apache
249-
250-
<Directory /var/www/project/public>
251-
Require all granted
252-
# ...
253-
</Directory>
254-
255-
For advanced Apache configuration options, read the official `Apache documentation`_.
256-
257-
.. _web-server-apache-fpm:
258-
259-
Apache with PHP-FPM
260-
-------------------
261-
262-
To make use of PHP-FPM with Apache, you first have to ensure that you have
263-
the FastCGI process manager ``php-fpm`` binary and Apache's FastCGI module
264-
installed (for example, on a Debian based system you have to install the
265-
``libapache2-mod-fastcgi`` and ``php<version>-fpm`` packages).
266-
267-
PHP-FPM uses so-called *pools* to handle incoming FastCGI requests. You can
268-
configure an arbitrary number of pools in the FPM configuration. In a pool
269-
you configure either a TCP socket (IP and port) or a Unix domain socket to
270-
listen on. Each pool can also be run under a different UID and GID:
271-
272-
.. code-block:: ini
273-
274-
; a pool called www
275-
[www]
276-
user = www-data
277-
group = www-data
278-
279-
; use a unix domain socket
280-
listen = /var/run/php/php-fpm.sock
281-
282-
; or listen on a TCP socket
283-
listen = 127.0.0.1:9000
284-
285-
Using mod_proxy_fcgi with Apache 2.4
286-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
287-
288-
If you are running Apache 2.4, you can use ``mod_proxy_fcgi`` to pass incoming
289-
requests to PHP-FPM. Configure PHP-FPM to listen on a TCP or Unix socket, enable
290-
``mod_proxy`` and ``mod_proxy_fcgi`` in your Apache configuration, and use the
291-
``SetHandler`` directive to pass requests for PHP files to PHP FPM:
292-
293-
.. code-block:: apache
294-
295-
<VirtualHost *:80>
296-
ServerName domain.tld
297-
ServerAlias www.domain.tld
298-
299-
# Uncomment the following line to force Apache to pass the Authorization
300-
# header to PHP: required for "basic_auth" under PHP-FPM and FastCGI
301-
#
302-
# SetEnvIfNoCase ^Authorization$ "(.+)" HTTP_AUTHORIZATION=$1
303-
304-
# For Apache 2.4.9 or higher
305-
# Using SetHandler avoids issues with using ProxyPassMatch in combination
306-
# with mod_rewrite or mod_autoindex
307-
<FilesMatch \.php$>
308-
SetHandler proxy:fcgi://127.0.0.1:9000
309-
# for Unix sockets, Apache 2.4.10 or higher
310-
# SetHandler proxy:unix:/path/to/fpm.sock|fcgi://dummy
311-
</FilesMatch>
312-
313-
# If you use Apache version below 2.4.9 you must consider update or use this instead
314-
# ProxyPassMatch ^/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/public/$1
315-
316-
# If you run your Symfony application on a subpath of your document root, the
317-
# regular expression must be changed accordingly:
318-
# ProxyPassMatch ^/path-to-app/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/public/$1
319-
320-
DocumentRoot /var/www/project/public
321-
<Directory /var/www/project/public>
322-
# enable the .htaccess rewrites
323-
AllowOverride All
324-
Require all granted
325-
</Directory>
326-
327-
# uncomment the following lines if you install assets as symlinks
328-
# or run into problems when compiling LESS/Sass/CoffeeScript assets
329-
# <Directory /var/www/project>
330-
# Options FollowSymlinks
331-
# </Directory>
332-
333-
ErrorLog /var/log/apache2/project_error.log
334-
CustomLog /var/log/apache2/project_access.log combined
335-
</VirtualHost>
336-
337-
PHP-FPM with Apache 2.2
338-
~~~~~~~~~~~~~~~~~~~~~~~
339-
340-
On Apache 2.2 or lower, you cannot use ``mod_proxy_fcgi``. You have to use
341-
the `FastCgiExternalServer`_ directive instead. Therefore, your Apache configuration
342-
should look something like this:
343-
344-
.. code-block:: apache
345-
346-
<VirtualHost *:80>
347-
ServerName domain.tld
348-
ServerAlias www.domain.tld
349-
350-
AddHandler php7-fcgi .php
351-
Action php7-fcgi /php7-fcgi
352-
Alias /php7-fcgi /usr/lib/cgi-bin/php7-fcgi
353-
FastCgiExternalServer /usr/lib/cgi-bin/php7-fcgi -host 127.0.0.1:9000 -pass-header Authorization
354-
355-
DocumentRoot /var/www/project/public
356-
<Directory /var/www/project/public>
357-
# enable the .htaccess rewrites
358-
AllowOverride All
359-
Order Allow,Deny
360-
Allow from all
361-
</Directory>
362-
363-
# uncomment the following lines if you install assets as symlinks
364-
# or run into problems when compiling LESS/Sass/CoffeeScript assets
365-
# <Directory /var/www/project>
366-
# Options FollowSymlinks
367-
# </Directory>
368-
369-
ErrorLog /var/log/apache2/project_error.log
370-
CustomLog /var/log/apache2/project_access.log combined
371-
</VirtualHost>
372-
373-
If you prefer to use a Unix socket, you have to use the ``-socket`` option
374-
instead:
375-
376-
.. code-block:: apache
377-
378-
FastCgiExternalServer /usr/lib/cgi-bin/php7-fcgi -socket /var/run/php/php-fpm.sock -pass-header Authorization
379-
380189
.. _`Apache documentation`: https://httpd.apache.org/docs/
381190
.. _`FastCgiExternalServer`: https://docs.oracle.com/cd/B31017_01/web.1013/q20204/mod_fastcgi.html#FastCgiExternalServer
382191
.. _`Nginx documentation`: https://www.nginx.com/resources/wiki/start/topics/recipes/symfony/

0 commit comments

Comments
 (0)