dotenv Configuration

Configuration modes for Panopticon

Normally, Panopticon's configuration is handled with the config.php file. This is a standard PHP class whose (public) properties store the configuration values for Panopticon. The contents of this file can be managed by the System Configuration page and CLI commands.

In some cases, it makes more sense to instead use .env files which are much easier to manage in deployment (e.g. Ansible) and other automation solutions.

Start using .env files

Panopticon includes a sample, inert file called .env.dist in its root. Copy this file to .env and edit it.

Caveats

When you are using .env files for configuration a few things in Panopticon work differently.

Panopticon will use the .env files instead of the config.php file. This means that the config.php file is not loaded at all.

Panopticon will not go through its installation process. If you are deploying a new installation of Panopticon you will need to install its database and create a new admin user through the command line. For example:

php cli/panopticon.php database:update
php cli/panopticon.php user:create --username=alice --password="P@s5_+=+_w0rD" --email="[email protected]" --name="Alice Administrator"

When you are using .env files you will not be taken through the Setup (installation) process. Trying to use it, e.g. by appending view=setup to the URL, will not result in any change to your installation.

When you are using .env files you will neither see nor be able to otherwise use the System Configuration page. You can only manage the configuration settings by editing the .env files.

When you are using .env files it does not make sense to use the config:create, config:maxtime:test, and config:set CLI commands. They will have no effect. Instead, set the configuration settings by editing the .env files.

Per-environment override files

Beyond the “standard” .env file in your installation's root, Panopticon can also load a file named .env.$PANOPTICON_ENVIRONMENT where $PANOPTICON_ENVIRONMENT is the value of the environment variable called PANOPTICON_ENVIRONMENT.

For example, if you have set export PANOPTICON_ENVIRONMENT=development in your .profile file, Panopticon will try to load the file .env.development.

If the PANOPTICON_ENVIRONMENT environment variable is not set, Panopticon assumes it contains the value production, therefore tries to load the file .env.production.

These override files are loaded after the main .env file (if it exists) and can override values already set in the main file, or set values which were not set at all in the main file. This is extremely useful if you are using a development-staging-live approach to deployment, with each deployment stage using its own database, mail server etc.

Clarification on the load order: if the main .env file exists, it's loaded before .env.$PANOPTICON_ENVIRONMENT. If the main .env file does not exist but the .env.$PANOPTICON_ENVIRONMENT exists, then only the .env.$PANOPTICON_ENVIRONMENT file is loaded. In both cases, the config.php file will NOT be loaded.

User Code override files

Beyond the override files mentioned above, Panopticon will also look for the .env and .env.$PANOPTICON_ENVIRONMENT files in the user_code directory, in this order. If any of them exists, it's loaded as an override to the main .env file.

This is very useful if you want to restore a backup of your live Panopticon installation to a development server. Put your dev server's configuration in user_code/.env and it will be loaded instead of the config.php file of the restored backup.

Clarification on the load order: if neither the .env nor the .env.$PANOPTICON_ENVIRONMENT file exists in the installation's root, but either or both of these files exist in the user_code folder then the files from the user_code folder will be loaded. In this case, the config.php file is NOT loaded at all.

Should you use .env files?

Generally speaking, if you have to ask this question the answer is most likely no. It's not the “normal” way to handle Panopticon's configuration, and it's decidedly not end-user–friendly by any stretch of the imagination.

The .env files support is there for a small number of expert users who want to automate the installation and maintenance of their Panopticon installation, or want to prevent even their Super Users from messing around with the Panopticon configuration. This is also something we use ourselves to handle the deployment of the same installation of Panopticon across different servers for development and testing purposes.

If you have a use case which could benefit from .env files and you are comfortable with editing configuration files then, sure, by all means, this was made for people like you.