Skip to content

docs: improve "Hosting with Apache" #7679

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Jul 11, 2023
Merged

docs: improve "Hosting with Apache" #7679

Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
b352160
docs: fix Section Headings marks
kenjis Jul 8, 2023
35e5342
docs: indent config values in sample
kenjis Jul 8, 2023
92e5a8f
docs: add sub section titles and fix
kenjis Jul 8, 2023
0a1e43a
docs: add new line
kenjis Jul 8, 2023
c917982
docs: change sub section order
kenjis Jul 8, 2023
fdf3252
docs: change sub section titles and level
kenjis Jul 8, 2023
18d5cf4
docs: change TOC depth to 3
kenjis Jul 8, 2023
eb465d9
docs: add ".. code-block:: apache"
kenjis Jul 8, 2023
9afea6f
docs: add new line
kenjis Jul 8, 2023
d98ec38
docs: change location of project folder and explanin folder structure
kenjis Jul 8, 2023
45165e1
docs: fix directory separator for Windows
kenjis Jul 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
206 changes: 127 additions & 79 deletions user_guide_src/source/installation/running.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
################
Running Your App
################

.. contents::
:local:
:depth: 2
:depth: 3

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

.. _initial-configuration:

*********************
Initial Configuration
=====================
*********************

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

************************
Local Development Server
========================
************************

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

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

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

*******************
Hosting with Apache
===================
*******************

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

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

.htaccess
---------
Configure Main Config File
==========================

Enabling mod_rewrite
--------------------

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

Make sure that the rewrite module is enabled (uncommented) in the main
configuration file, e.g., **apache2/conf/httpd.conf**::
configuration file, e.g., **apache2/conf/httpd.conf**:

.. code-block:: apache

LoadModule rewrite_module modules/mod_rewrite.so

Setting Document Root
---------------------

Also make sure that the default document root's ``<Directory>`` element enables this too,
in the ``AllowOverride`` setting::
in the ``AllowOverride`` setting:

.. code-block:: apache

<Directory "/opt/lamp/apache2/htdocs">
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
</Directory>

Removing the index.php
----------------------

See :ref:`CodeIgniter URLs <urls-remove-index-php-apache>`.

Virtual Hosting
---------------
Hosting with VirtualHost
========================

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

Enabling vhost_alias_module
---------------------------

Make sure that the virtual hosting module is enabled (uncommented) in the main
configuration file, e.g., **apache2/conf/httpd.conf**::
configuration file, e.g., **apache2/conf/httpd.conf**:

.. code-block:: apache

LoadModule vhost_alias_module modules/mod_vhost_alias.so

Adding Host Alias
-----------------

Add a host alias in your "hosts" file, typically **/etc/hosts** on unix-type platforms,
or **c:/Windows/System32/drivers/etc/hosts** on Windows.
Add a line to the file. This could be ``myproject.local`` or ``myproject.test``, for instance::
or **c:\Windows\System32\drivers\etc\hosts** on Windows.

Add a line to the file.
This could be ``myproject.local`` or ``myproject.test``, for instance::

127.0.0.1 myproject.local

Setting VirtualHost
-------------------

Add a ``<VirtualHost>`` element for your webapp inside the virtual hosting configuration,
e.g., **apache2/conf/extra/httpd-vhost.conf**::
e.g., **apache2/conf/extra/httpd-vhost.conf**:

.. code-block:: apache

<VirtualHost *:80>
DocumentRoot "/opt/lamp/apache2/htdocs/myproject/public"
ServerName myproject.local
ErrorLog "logs/myproject-error_log"
CustomLog "logs/myproject-access_log" common
DocumentRoot "/opt/lamp/apache2/myproject/public"
ServerName myproject.local
ErrorLog "logs/myproject-error_log"
CustomLog "logs/myproject-access_log" common

<Directory "/opt/lamp/apache2/myproject/public">
AllowOverride All
Require all granted
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think I've used this directive before. Is it necessary? Secure? Advised?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it was documented:

If your project folder is not a subfolder of the Apache document root, then your
<VirtualHost> element may need a nested <Directory> element to grant the web server access to the files.

/opt/lamp/apache2/htdocs/myproject/public is in the main document root /opt/lamp/apache2/htdocs.
It is not good. So I moved it.

</Directory>
</VirtualHost>

If your project folder is not a subfolder of the Apache document root, then your
``<VirtualHost>`` element may need a nested ``<Directory>`` element to grant the web server access to the files.
The above configuration assumes the project folder is located as follows:

.. code-block:: text

With mod_userdir (Shared Hosts)
--------------------------------
apache2/
├── myproject/ (Project Folder)
│ └── public/ (DocumentRoot for myproject.local)
└── htdocs/

Testing
-------

With the above configuration, your webapp would be accessed with the URL **http://myproject.local/** in your browser.

Apache needs to be restarted whenever you change its configuration.

Hosting with mod_userdir (Shared Hosts)
=======================================

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.

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>`_.

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).

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**::
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**:

.. code-block:: apache

UserDir public_html

So you will need to configure Apache to look for CodeIgniter's public directory first before trying to serve the default::
So you will need to configure Apache to look for CodeIgniter's public directory first before trying to serve the default:

.. code-block:: apache

UserDir "public_html/public" "public_html"

Be sure to specify options and permissions for the CodeIgniter public directory as well. A **userdir.conf** might look like::
Be sure to specify options and permissions for the CodeIgniter public directory as well. A **userdir.conf** might look like:

.. code-block:: apache

<IfModule mod_userdir.c>
UserDir "public_html/public" "public_html"
UserDir disabled root

<Directory /home/*/public_html>
AllowOverride All
Options MultiViews Indexes FollowSymLinks
<Limit GET POST OPTIONS>
# Apache <= 2.2:
# Order allow,deny
# Allow from all

# Apache >= 2.4:
Require all granted
</Limit>
<LimitExcept GET POST OPTIONS>
# Apache <= 2.2:
# Order deny,allow
# Deny from all

# Apache >= 2.4:
Require all denied
</LimitExcept>
AllowOverride All
Options MultiViews Indexes FollowSymLinks
<Limit GET POST OPTIONS>
# Apache <= 2.2:
# Order allow,deny
# Allow from all

# Apache >= 2.4:
Require all granted
Comment on lines +229 to +230
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah I see, it looks like this is a new approach. I trust you on this.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you mean? The change here is simply a change in indentation.

</Limit>
<LimitExcept GET POST OPTIONS>
# Apache <= 2.2:
# Order deny,allow
# Deny from all

# Apache >= 2.4:
Require all denied
</LimitExcept>
</Directory>

<Directory /home/*/public_html/public>
AllowOverride All
Options MultiViews Indexes FollowSymLinks
<Limit GET POST OPTIONS>
# Apache <= 2.2:
# Order allow,deny
# Allow from all

# Apache >= 2.4:
Require all granted
</Limit>
<LimitExcept GET POST OPTIONS>
# Apache <= 2.2:
# Order deny,allow
# Deny from all

# Apache >= 2.4:
Require all denied
</LimitExcept>
AllowOverride All
Options MultiViews Indexes FollowSymLinks
<Limit GET POST OPTIONS>
# Apache <= 2.2:
# Order allow,deny
# Allow from all

# Apache >= 2.4:
Require all granted
</Limit>
<LimitExcept GET POST OPTIONS>
# Apache <= 2.2:
# Order deny,allow
# Deny from all

# Apache >= 2.4:
Require all denied
</LimitExcept>
</Directory>
</IfModule>

Setting Environment
-------------------

See :ref:`Handling Multiple Environments <environment-apache>`.
Removing the index.php
======================

Testing
-------
See :ref:`CodeIgniter URLs <urls-remove-index-php-apache>`.

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

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

******************
Hosting with Nginx
==================
******************

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

default.conf
------------
============

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

Expand Down Expand Up @@ -269,12 +316,13 @@ This configuration enables URLs without "index.php" in them and using CodeIgnite
}

Setting Environment
-------------------
===================

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

*********************
Bootstrapping the App
=====================
*********************

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