configuration.php and .htaccess

The installer writes configuration.php in the site root as the last step of the installation. The file contains one class, JConfig, whose public properties are the settings. During bootstrap, includes/framework.php checks that the file exists and is larger than ten bytes, includes it, and builds the application configuration from an instance of that class. If the file is missing and no installation folder exists, Joomla stops with the message that no configuration file was found and no installation code is available; if the installation folder is still present, the web installer starts. The location is held in the constant JPATH_CONFIGURATION, which includes/defines.php sets to the site root. A defines.php file placed next to index.php is included first and can override it, which is how some hosts keep the file outside the code tree.

Two consequences matter in practice. The file is plain PHP, so a syntax error (a missing semicolon after an edit) takes the whole site down with a blank page or a fatal error before any Joomla error page can be rendered. And because the class is instantiated on every request, anything that is valid PHP in a property default or in a constructor is evaluated every time; that is useful for reading environment variables (see below) and harmful for slow code.

The properties are read through the application, $app->get('name'), never by reading the file again. Extensions that need a setting use the application object (or the injected configuration), and Factory::getConfig() has been deprecated for that reason. The same registry backs the CLI commands config:get and config:set.

The installer template is installation/configuration.php-dist in the source tree. It groups the properties with comments; the groups below follow it. Properties in parentheses are the ones a normal installation fills in differently from the template.

Source: Joomla CMS source: configuration.php-dist

A few properties exist in the file but not on the Global Configuration screen. dbprefix, dbtype, host, user, db and the dbssl* values can only be changed by editing the file or with config:set; live_site has no field at all; and asset_id must be left alone because it ties the file to the root row of the permissions tree in the database. Older installations can contain extra properties that current releases ignore, such as ftp_* values from the days of the FTP layer or the root_user property that the installer left behind in Joomla 3; the Global Configuration model can remove root_user on request, so a file with one is not an error.

A file that is committed or baked into an image cannot contain real credentials. PHP allows an expression in a constructor, so the JConfig class can read the environment. The following file is the deployment template for the Tallpine site; nothing in it is a real secret, and the values come from variables set by Docker Compose, Kubernetes or the host’s service manager.

Source: Joomla CMS source: configuration.php-dist

Compose passes the variables (a .env file kept out of version control, or a secrets mechanism, supplies the values):

Source: Docker Official Image: joomla

Mounting the file read-only is the strongest way to keep Global Configuration from rewriting it, and the screen’s notice that configuration.php is not writable is then expected rather than a fault. The official image itself reads JOOMLA_DB_HOST, JOOMLA_DB_USER, JOOMLA_DB_PASSWORD (or JOOMLA_DB_PASSWORD_FILE), JOOMLA_DB_NAME and JOOMLA_DB_TYPE during its first start, and writes a normal file; the image variables only seed the installation, and changing them afterwards does nothing. Container operations are covered in Compose for local development and Local Development with Docker; on Kubernetes, the database password and the secret belong in a Secret object, described in Kubernetes Secrets. When sessions or cache move to Redis, the session_redis_* and redis_* properties hold the host, port and AUTH value (a secret too); see Redis Reference for the server side.

The pitfall that the comment in the template mentions is how Global Configuration saves. The model builds the new file from the submitted form data, and for the protected fields (password, secret, smtppass, the OAuth2 mail values and the Redis AUTH values) it takes the current values from the running application. When an administrator presses Save, the values that the constructor read from the environment are written into the file as literals. On a deployment that is meant to be environment-driven, mount the file read-only or never save the screen on that host.

Joomla keeps the file read-only. When Global Configuration saves, it switches the file to mode 0644 if the PHP user owns it, rewrites it as a PHP class named JConfig, and sets it back to 0444. The rewritten file is regenerated from the submitted values, which has two consequences: comments and custom code in the file are lost, and properties that are not known to the form are kept only if they were loaded. Hand-written constructors, as in the previous section, do not survive a save.

The recommended procedure for a manual edit is:

Source: Joomla User Guide: Global Configuration

The command line avoids the editor altogether and validates what it writes:

Source: Joomla User Guide: Using the CLI

config:set takes option=value pairs, checks the database connection when database options change, validates the prefix against the same rules as the installer, and calls the same model as the screen, so it also runs the force_ssl check, the path checks and the protected-field handling. More commands are in Command Line Interface.

The permission model is as follows.

Never keep configuration.php in version control with real values. Keep a template in the repository (as above) and keep the real file in the secret store. The repository’s secret scanner will otherwise flag the file, and a leaked file means a leaked database password and secret. Hosting panels often show the file in a file manager with 0644; check the mode after every restore, because a restored backup rewrites it. Joomla’s Security Centre and the hardening checklist in Security Hardening, MFA and Passkeys list the same measures.

Joomla ships htaccess.txt in the site root. Apache only reads a file called .htaccess (the name is set by the AccessFileName directive), so the file is activated by copying or renaming it. If the host already provides an .htaccess with its own rules, merge the two rather than replacing it. The User Guide recommends editing .htaccess rather than htaccess.txt, because updates can overwrite the latter, and after a Joomla update it is worth comparing your .htaccess with the current htaccess.txt, since the file changes between versions (the SEF section, for example, gained the API application rules in Joomla 4). Older books and tutorials show the Joomla 3 or 4 contents of this file; Developing Extensions for Joomla! 5 (Packt, 2023) and Joomla! 4 Masterclass (Packt, 2023) predate the current layout and do not describe the API rewrite or the pre-compressed asset section.

Source: Joomla User Guide: The htaccess.txt file

The 6.2 file has these sections, in order.

Source: Joomla CMS source: htaccess.txt

The file is only half of the story. The Use URL Rewriting option of Global Configuration (the sef_rewrite property) removes index.php from generated URLs; the rewrite rules make those URLs work. Turning the option on without the file, or on a server where AllowOverride is None, makes every page except the home page return 404. The related checklist (FollowSymlinks, AllowOverride All, the module list) is in SEO, SEF URLs, Redirects and Schema.org. OpenLiteSpeed reads .htaccess but caches it: restart the server after a change.

Security reasoning: Apache’s .htaccess is convenient but costs a file-system lookup per request and lets every writable directory carry its own rules. If you control the server, place the same directives in the virtual host and set AllowOverride None; the rules above translate one to one.

Source: Joomla CMS source: htaccess.txt

nginx ignores .htaccess. The User Guide pages on SEF URLs with nginx and on nginx hosting notes give the short form: a try_files fallback to index.php, PHP handed to PHP-FPM, a long expiry for static files and a deny rule for scripts in writable folders. On Joomla 4.0 and later the API application needs its own location, which older nginx notes do not mention and which is the usual reason that the Web Services API and the headless front end fail with 404 on nginx.

Source: Joomla User Guide: SEF URLs on Nginx

Points to check: with the public folder root points to the public directory and configuration.php is not reachable at all; without it, add location = /configuration.php { deny all; } and deny the libraries, cache and tmp directories too. Test the exploit filter with a request such as ?x=GLOBALS[a]=1, which must return 403. The HTTP_AUTHORIZATION line forwards the Authorization header to PHP-FPM, which the API token authentication needs. The nginx notes page in the User Guide is older than Joomla 4; its sample targets PHP 5 era sockets and a return 403 followed by an error_page line that never runs, so adapt it rather than copying it.

Microsoft IIS reads web.config. Joomla ships web.config.txt, which is renamed to web.config and requires the URL Rewrite Module. It contains three rules with the same logic as htaccess.txt: Joomla! Common Exploits Prevention (four query-string conditions, returns 403 and stops processing), Joomla! API Application SEF URLs (rewrites to api/index.php) and Joomla! Public Frontend SEF URLs (rewrites to index.php), together with directoryBrowse enabled="false" and an X-Content-Type-Options: nosniff header; the cross-origin headers are commented out as in the Apache file. It has no counterpart for the SVG header or the pre-compressed assets: if you need them, add a customHeaders entry and enable IIS static compression. IIS is a supported platform (the Developer Manual lists IIS 10), unlike Drupal where IIS support was removed in 11.0.

Source: Joomla CMS source: web.config.txt

The block above is the shipped file without the exploit-prevention rule and the commented headers. Hide the writable folders with the IIS request filtering feature and the configuration.php file with a hiddenSegments entry if the code tree is under the site root.

The User Guide documents moving a site between subdirectories and gives general migration advice (back up first, test on a copy, check extension compatibility); the host-to-host steps below follow the same logic and the file format described above. Use a backup tool or a manual copy; Joomla has no built-in backup (see Backups and Recovery).

Source: Joomla User Guide: Moving Installation Directory

The same list explains the two common failures after a move. A site that shows the installer was copied without configuration.php (or with an empty one). A site that loads but shows no styling or sends users to the old domain still has live_site set, or its .htaccess carries an old redirect. Moving to a subdirectory or from one removes the subdirectory from log_path, tmp_path and live_site and from the RewriteBase line; the User Guide page lists $ftp_root too, which only exists in files created by old releases. Moving between environments that share a code base (staging to production) is better done with deployments plus a separate database restore than by copying the configuration.

On a cloud deployment, the same file is the reason why more than one web node needs shared state: with more than one machine, session_handler, the system cache and the tmp and images folders have to be shared or externalised, and the database must be a separate service. That topic is in Multi-site Options and Scaling.