Skip to content

Commit 6cedbe9

Browse files
kenjiskenjis
authored
Merge pull request #7679 from kenjis/docs-apache-config
docs: improve "Hosting with Apache"
2 parents d778ec3 + 45165e1 commit 6cedbe9

1 file changed

Lines changed: 127 additions & 79 deletions

File tree

‎user_guide_src/source/installation/running.rst‎

Lines changed: 127 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
1+
################
12
Running Your App
23
################
34

45
.. contents::
56
:local:
6-
:depth: 2
7+
:depth: 3
78

89
A CodeIgniter 4 app can be run in a number of different ways: hosted on a web server,
910
using virtualization, or using CodeIgniter's command line tool for testing.
@@ -20,8 +21,9 @@ section of the User Guide to begin learning how to build dynamic PHP application
2021

2122
.. _initial-configuration:
2223

24+
*********************
2325
Initial Configuration
24-
=====================
26+
*********************
2527

2628
#. Open the **app/Config/App.php** file with a text editor and
2729
set your base URL to ``$baseURL``. If you need more flexibility, the baseURL may
@@ -49,11 +51,12 @@ Initial Configuration
4951
your project, so that it is writable by the user or account used by your
5052
web server.
5153

54+
************************
5255
Local Development Server
53-
========================
56+
************************
5457

5558
CodeIgniter 4 comes with a local development server, leveraging PHP's built-in web server
56-
with CodeIgniter routing. You can launch it, with the following command line
59+
with CodeIgniter routing. You can launch it, with the following command line
5760
in the main directory::
5861

5962
> php spark serve
@@ -83,156 +86,200 @@ The local development server can be customized with three command line options:
8386

8487
> php spark serve --php /usr/bin/php7.6.5.4
8588

89+
*******************
8690
Hosting with Apache
87-
===================
91+
*******************
8892

8993
A CodeIgniter4 webapp is normally hosted on a web server.
9094
Apache HTTP Server is the "standard" platform, and assumed in much of our documentation.
9195

9296
Apache is bundled with many platforms, but can also be downloaded in a bundle
9397
with a database engine and PHP from `Bitnami <https://bitnami.com/stacks/infrastructure>`_.
9498

95-
.htaccess
96-
---------
99+
Configure Main Config File
100+
==========================
101+
102+
Enabling mod_rewrite
103+
--------------------
97104

98105
The "mod_rewrite" module enables URLs without "index.php" in them, and is assumed
99106
in our user guide.
100107

101108
Make sure that the rewrite module is enabled (uncommented) in the main
102-
configuration file, e.g., **apache2/conf/httpd.conf**::
109+
configuration file, e.g., **apache2/conf/httpd.conf**:
110+
111+
.. code-block:: apache
103112
104113
LoadModule rewrite_module modules/mod_rewrite.so
105114
115+
Setting Document Root
116+
---------------------
117+
106118
Also make sure that the default document root's ``<Directory>`` element enables this too,
107-
in the ``AllowOverride`` setting::
119+
in the ``AllowOverride`` setting:
120+
121+
.. code-block:: apache
108122
109123
<Directory "/opt/lamp/apache2/htdocs">
110124
Options Indexes FollowSymLinks
111125
AllowOverride All
112126
Require all granted
113127
</Directory>
114128
115-
Removing the index.php
116-
----------------------
117-
118-
See :ref:`CodeIgniter URLs <urls-remove-index-php-apache>`.
119-
120-
Virtual Hosting
121-
---------------
129+
Hosting with VirtualHost
130+
========================
122131

123132
We recommend using "virtual hosting" to run your apps.
124133
You can set up different aliases for each of the apps you work on,
125134

135+
Enabling vhost_alias_module
136+
---------------------------
137+
126138
Make sure that the virtual hosting module is enabled (uncommented) in the main
127-
configuration file, e.g., **apache2/conf/httpd.conf**::
139+
configuration file, e.g., **apache2/conf/httpd.conf**:
140+
141+
.. code-block:: apache
128142
129143
LoadModule vhost_alias_module modules/mod_vhost_alias.so
130144
145+
Adding Host Alias
146+
-----------------
147+
131148
Add a host alias in your "hosts" file, typically **/etc/hosts** on unix-type platforms,
132-
or **c:/Windows/System32/drivers/etc/hosts** on Windows.
133-
Add a line to the file. This could be ``myproject.local`` or ``myproject.test``, for instance::
149+
or **c:\Windows\System32\drivers\etc\hosts** on Windows.
150+
151+
Add a line to the file.
152+
This could be ``myproject.local`` or ``myproject.test``, for instance::
134153

135154
127.0.0.1 myproject.local
136155

156+
Setting VirtualHost
157+
-------------------
158+
137159
Add a ``<VirtualHost>`` element for your webapp inside the virtual hosting configuration,
138-
e.g., **apache2/conf/extra/httpd-vhost.conf**::
160+
e.g., **apache2/conf/extra/httpd-vhost.conf**:
161+
162+
.. code-block:: apache
139163
140164
<VirtualHost *:80>
141-
DocumentRoot "/opt/lamp/apache2/htdocs/myproject/public"
142-
ServerName myproject.local
143-
ErrorLog "logs/myproject-error_log"
144-
CustomLog "logs/myproject-access_log" common
165+
DocumentRoot "/opt/lamp/apache2/myproject/public"
166+
ServerName myproject.local
167+
ErrorLog "logs/myproject-error_log"
168+
CustomLog "logs/myproject-access_log" common
169+
170+
<Directory "/opt/lamp/apache2/myproject/public">
171+
AllowOverride All
172+
Require all granted
173+
</Directory>
145174
</VirtualHost>
146175
147-
If your project folder is not a subfolder of the Apache document root, then your
148-
``<VirtualHost>`` element may need a nested ``<Directory>`` element to grant the web server access to the files.
176+
The above configuration assumes the project folder is located as follows:
177+
178+
.. code-block:: text
149179
150-
With mod_userdir (Shared Hosts)
151-
--------------------------------
180+
apache2/
181+
├── myproject/ (Project Folder)
182+
│ └── public/ (DocumentRoot for myproject.local)
183+
└── htdocs/
184+
185+
Testing
186+
-------
187+
188+
With the above configuration, your webapp would be accessed with the URL **http://myproject.local/** in your browser.
189+
190+
Apache needs to be restarted whenever you change its configuration.
191+
192+
Hosting with mod_userdir (Shared Hosts)
193+
=======================================
152194

153195
A common practice in shared hosting environments is to use the Apache module "mod_userdir" to enable per-user Virtual Hosts automatically. Additional configuration is required to allow CodeIgniter4 to be run from these per-user directories.
154196

155197
The following assumes that the server is already configured for mod_userdir. A guide to enabling this module is available `in the Apache documentation <https://httpd.apache.org/docs/2.4/howto/public_html.html>`_.
156198

157199
Because CodeIgniter4 expects the server to find the framework front controller at **public/index.php** by default, you must specify this location as an alternative to search for the request (even if CodeIgniter4 is installed within the per-user web directory).
158200

159-
The default user web directory **~/public_html** is specified by the ``UserDir`` directive, typically in **apache2/mods-available/userdir.conf** or **apache2/conf/extra/httpd-userdir.conf**::
201+
The default user web directory **~/public_html** is specified by the ``UserDir`` directive, typically in **apache2/mods-available/userdir.conf** or **apache2/conf/extra/httpd-userdir.conf**:
202+
203+
.. code-block:: apache
160204
161205
UserDir public_html
162206
163-
So you will need to configure Apache to look for CodeIgniter's public directory first before trying to serve the default::
207+
So you will need to configure Apache to look for CodeIgniter's public directory first before trying to serve the default:
208+
209+
.. code-block:: apache
164210
165211
UserDir "public_html/public" "public_html"
166212
167-
Be sure to specify options and permissions for the CodeIgniter public directory as well. A **userdir.conf** might look like::
213+
Be sure to specify options and permissions for the CodeIgniter public directory as well. A **userdir.conf** might look like:
214+
215+
.. code-block:: apache
168216
169217
<IfModule mod_userdir.c>
170218
UserDir "public_html/public" "public_html"
171219
UserDir disabled root
172220
173221
<Directory /home/*/public_html>
174-
AllowOverride All
175-
Options MultiViews Indexes FollowSymLinks
176-
<Limit GET POST OPTIONS>
177-
# Apache <= 2.2:
178-
# Order allow,deny
179-
# Allow from all
180-
181-
# Apache >= 2.4:
182-
Require all granted
183-
</Limit>
184-
<LimitExcept GET POST OPTIONS>
185-
# Apache <= 2.2:
186-
# Order deny,allow
187-
# Deny from all
188-
189-
# Apache >= 2.4:
190-
Require all denied
191-
</LimitExcept>
222+
AllowOverride All
223+
Options MultiViews Indexes FollowSymLinks
224+
<Limit GET POST OPTIONS>
225+
# Apache <= 2.2:
226+
# Order allow,deny
227+
# Allow from all
228+
229+
# Apache >= 2.4:
230+
Require all granted
231+
</Limit>
232+
<LimitExcept GET POST OPTIONS>
233+
# Apache <= 2.2:
234+
# Order deny,allow
235+
# Deny from all
236+
237+
# Apache >= 2.4:
238+
Require all denied
239+
</LimitExcept>
192240
</Directory>
193241
194242
<Directory /home/*/public_html/public>
195-
AllowOverride All
196-
Options MultiViews Indexes FollowSymLinks
197-
<Limit GET POST OPTIONS>
198-
# Apache <= 2.2:
199-
# Order allow,deny
200-
# Allow from all
201-
202-
# Apache >= 2.4:
203-
Require all granted
204-
</Limit>
205-
<LimitExcept GET POST OPTIONS>
206-
# Apache <= 2.2:
207-
# Order deny,allow
208-
# Deny from all
209-
210-
# Apache >= 2.4:
211-
Require all denied
212-
</LimitExcept>
243+
AllowOverride All
244+
Options MultiViews Indexes FollowSymLinks
245+
<Limit GET POST OPTIONS>
246+
# Apache <= 2.2:
247+
# Order allow,deny
248+
# Allow from all
249+
250+
# Apache >= 2.4:
251+
Require all granted
252+
</Limit>
253+
<LimitExcept GET POST OPTIONS>
254+
# Apache <= 2.2:
255+
# Order deny,allow
256+
# Deny from all
257+
258+
# Apache >= 2.4:
259+
Require all denied
260+
</LimitExcept>
213261
</Directory>
214262
</IfModule>
215263
216-
Setting Environment
217-
-------------------
218-
219-
See :ref:`Handling Multiple Environments <environment-apache>`.
264+
Removing the index.php
265+
======================
220266

221-
Testing
222-
-------
267+
See :ref:`CodeIgniter URLs <urls-remove-index-php-apache>`.
223268

224-
With the above configuration, your webapp would be accessed with the URL **http://myproject.local/** in your browser.
269+
Setting Environment
270+
===================
225271

226-
Apache needs to be restarted whenever you change its configuration.
272+
See :ref:`Handling Multiple Environments <environment-apache>`.
227273

274+
******************
228275
Hosting with Nginx
229-
==================
276+
******************
230277

231278
Nginx is the second most widely used HTTP server for web hosting.
232279
Here you can find an example configuration using PHP 8.1 FPM (unix sockets) under Ubuntu Server.
233280

234281
default.conf
235-
------------
282+
============
236283

237284
This configuration enables URLs without "index.php" in them and using CodeIgniter's "404 - File Not Found" for URLs ending with ".php".
238285

@@ -269,12 +316,13 @@ This configuration enables URLs without "index.php" in them and using CodeIgnite
269316
}
270317
271318
Setting Environment
272-
-------------------
319+
===================
273320

274321
See :ref:`Handling Multiple Environments <environment-nginx>`.
275322

323+
*********************
276324
Bootstrapping the App
277-
=====================
325+
*********************
278326

279327
In some scenarios you will want to load the framework without actually running the whole
280328
application. This is particularly useful for unit testing your project, but may also be

0 commit comments

Comments
 (0)