Configuration under version control #

This page is for IT teams in public bodies whose change process says that every change to a production system must be traceable to an approved request. It answers how to keep an Exponential site's code and settings in version control, how to stop the administration from changing settings on the server behind your process, and what must stay out of the repository. The feature reference is Configuration managed by the deployment.

Contents #

1. What belongs in version control
2. The problem with settings edited in the browser
3. Locking it with ManagedByDeployment
4. Secrets
5. Traceability
6. Checklist

What belongs in version control #

How code reaches a server with Composer and Git is on Composer and Git on servers.

The problem with settings edited in the browser #

Without a lock, the INI editor, the toolbar and menu editors and the template editor of the administration write *.ini.append.php and .tpl files into the release directory. Version control does not see them, and the next deployment drops them (Configuration managed by the deployment). For a public body this is also an audit finding: a production change that bypassed the change process.

Locking it with ManagedByDeployment #

One switch per siteaccess, off by default, since 6.0.15:

# settings/siteaccess/<admin siteaccess>/site.ini.append.php
[ConfigurationSettings]
ManagedByDeployment=enabled

With it enabled, in web requests:

• the views that write configuration answer like a disabled view (by default a 404): settings/edit, the toolbar and menu editors, the template editor, the setup wizard, extension activation (setup/extensions), the code generators and package upload, install, uninstall, create and export;
• menus and links to those views are hidden;
• eZINI::save() refuses, which also stops writers the list does not know.

What stays open: read-only views (settings/view, setup/cache, setup/info, the logs), command line scripts and the deployment itself, including exp:ini and bin/php/*.php, and key material the code generates on first use (the audit keys, the mail preference secret). The list of locked views lives in the class, not in an INI file, so a settings file cannot weaken it. It applies under PHP-FPM, Apache, FrankenPHP and Velocity alike.

Limits: installing a package from the command line still writes to the database, and file permissions on the release directory remain the stronger measure.

Put the setting itself in version control, never in a file the administration could write. Settings changes then go through your repository, your review and your deployment:

./console exp:ini get site.ini/ConfigurationSettings/ManagedByDeployment --allow-root-user

Secrets #

Keep database passwords and generated keys out of the repository, or encrypted in it:

A common pattern is a small, unversioned settings file per environment for the credentials, deployed from your secrets store. Back those files up separately (Keys and secrets in backups).

Traceability #

With code and settings in version control, the history of the repository says what changed, when and in which reviewed commit. Exponential adds its side: the audit trail records settings writes, cache clears, deploys and package installs in the system channel (Audit trail). Together they let you answer an auditor's "who changed this setting, and was it approved?". The change process itself is described on Change management and advisory boards.

Checklist #

• To do: Code, extensions, designs and settings are in version control; var/, vendor/ and config.env.php are not.
• To do: Secrets are kept out of the repository or encrypted in it.
• To do: ManagedByDeployment=enabled on every administration and editor siteaccess of production.
• To do: The release directory is not writable by the web server's user where nothing needs to write it.
• To do: Deployments run from the repository, not by hand edits on the server.

Related pages #

• Hosting index of this folder
• Managed by deployment in the change pages
• Deploying changes
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.