## 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:
```bash
php cli/panopticon.php database:update
php cli/panopticon.php user:create --username=alice --password="P@s5_+=+_w0rD" --email="alice@example.com" --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.