diff --git a/user_guide_src/source/installation/running.rst b/user_guide_src/source/installation/running.rst index 0b974180f7e7..eda284684642 100644 --- a/user_guide_src/source/installation/running.rst +++ b/user_guide_src/source/installation/running.rst @@ -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. @@ -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 @@ -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 @@ -83,8 +86,9 @@ 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. @@ -92,19 +96,29 @@ Apache HTTP Server is the "standard" platform, and assumed in much of our docume Apache is bundled with many platforms, but can also be downloaded in a bundle with a database engine and PHP from `Bitnami `_. -.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 ```` element enables this too, -in the ``AllowOverride`` setting:: +in the ``AllowOverride`` setting: + +.. code-block:: apache Options Indexes FollowSymLinks @@ -112,43 +126,71 @@ in the ``AllowOverride`` setting:: Require all granted -Removing the index.php ----------------------- - -See :ref:`CodeIgniter URLs `. - -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 ```` 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 - 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 + + + AllowOverride All + Require all granted + -If your project folder is not a subfolder of the Apache document root, then your -```` element may need a nested ```` 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. @@ -156,83 +198,88 @@ The following assumes that the server is already configured for mod_userdir. A g 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 UserDir "public_html/public" "public_html" UserDir disabled root - AllowOverride All - Options MultiViews Indexes FollowSymLinks - - # Apache <= 2.2: - # Order allow,deny - # Allow from all - - # Apache >= 2.4: - Require all granted - - - # Apache <= 2.2: - # Order deny,allow - # Deny from all - - # Apache >= 2.4: - Require all denied - + AllowOverride All + Options MultiViews Indexes FollowSymLinks + + # Apache <= 2.2: + # Order allow,deny + # Allow from all + + # Apache >= 2.4: + Require all granted + + + # Apache <= 2.2: + # Order deny,allow + # Deny from all + + # Apache >= 2.4: + Require all denied + - AllowOverride All - Options MultiViews Indexes FollowSymLinks - - # Apache <= 2.2: - # Order allow,deny - # Allow from all - - # Apache >= 2.4: - Require all granted - - - # Apache <= 2.2: - # Order deny,allow - # Deny from all - - # Apache >= 2.4: - Require all denied - + AllowOverride All + Options MultiViews Indexes FollowSymLinks + + # Apache <= 2.2: + # Order allow,deny + # Allow from all + + # Apache >= 2.4: + Require all granted + + + # Apache <= 2.2: + # Order deny,allow + # Deny from all + + # Apache >= 2.4: + Require all denied + -Setting Environment -------------------- - -See :ref:`Handling Multiple Environments `. +Removing the index.php +====================== -Testing -------- +See :ref:`CodeIgniter URLs `. -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 `. +****************** 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". @@ -269,12 +316,13 @@ This configuration enables URLs without "index.php" in them and using CodeIgnite } Setting Environment -------------------- +=================== See :ref:`Handling Multiple Environments `. +********************* 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