Set up environment-specific settings
This task is for administrators and developers who run development, test and production copies of a public website. At the end each machine knows its environment and reads the right settings automatically (Settings per environment).
Contents
Before you start
- Shell access on each machine.
- A list of what differs per environment (mail, debug, databases, the admin badge).
Steps
On each machine, copy the example and set the name (
dev,test,prodor your own: lowercase letters, digits,-or_, starting with a letter, at most 32 characters):cp config.env.php.example config.env.phpdefine( 'EXP_ENV', 'test' );config.env.phpis kept out of version control by.gitignore.Put the differences in variant files next to the standard ones, the environment name right after
.ini:# settings/override/site.ini.test.append.php [MailSettings] Transport=file [DebugSettings] DebugOutput=enabled DebugByIP=enabled DebugIPList[] DebugIPList[]=192.0.2.10/32 ; tester workstation */ ?>The variant files go into version control; only
config.env.phpdiffers per machine.Clear the INI cache once (
php bin/php/ezcache.php --clear-tag=ini --allow-root-user); each environment has its own cache files afterwards.Optional:
site.ini [AdminEnvironment] Level=autoshows the environment as a badge in the admin4 header and sign-in page.
Check it worked
./console exp:ini get 'site.ini/MailSettings/Transport' --allow-root-userprints file on the test machine and your mail transport on production. Templates can test {exp_environment()}.
Pitfalls
devandtestturn PHP'sdisplay_errorson inindex.php; never set them on production.settings/overridestill outranks siteaccess settings; a variant overrides only its own layer.- Without
EXP_ENV, exactly the old files are read; an invalid name counts as none (and is noted in the PHP error log).
Related pages
- Environments: development, test and production
- Staging and approval
- Mail problems
- Lock configuration with ManagedByDeployment
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.