-
-
Notifications
You must be signed in to change notification settings - Fork 20
dotenv Configuration
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.
Panopticon includes a sample, inert file called .env.dist
in its root. Copy this file to .env
and edit it.
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="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.
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.
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.
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.
Documentation Copyright ©2023–2024 Akeeba Ltd.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
You can also obtain a copy of the GNU Free Documentation License from the Free Software Foundation
- Overview pages
- Working with sites
- Site Overview
- Backup Management with Akeeba Backup Pro
- Security Management with Admin Tools Pro
- Scheduled Update Summary
- Scheduled Action Summary
- Backup Tasks
- Scanner Tasks
- System Configuration
- Managing Sites
- Mail templates
- Users and Groups
- Tasks
- Log files
- Update Panopticon
- Database Backups
- Fixing your session save path
- The .htaccess file
- Advanced Customisation (user code)
- Plugins
- Custom CSS
- Custom Templates
- Advanced Permissions
- .env For Configuration