Each web application on the servers has an environment file: a list of settings, one KEY=value per line, that the application reads. Ploi Env Tool keeps a set of those settings for each environment and, when you save, writes them into the environment file of every matching site through Ploi. It changes many sites in one click, so read what it does before using it.
Who can use it
Ploi Env Tool is in the side menu of the admin panel. To reach the panel, open the menu at the top right and choose Go To Admin Panel. Only super administrators see the entry and can open the page; anyone else gets a 405 error page.
The page
The page has four sections:
- All sites: settings written to every site, whatever its environment.
- Production, Development and Staging: settings written only to the sites of that environment.
A site gets the All sites settings plus those of its own environment. When the same key is in both, the environment's value wins.
Each section has a table with Key, Value, Enabled and Action, which holds each row's Remove button, and below it Matching sites: the sites the section writes to, each with its domain, project, server and environment. Only applications set up on Ploi, on a server with a Ploi Id, are listed. With none, it says No Ploi sites currently match this environment. How applications are set up is in Servers and applications.
The values are kept encrypted, but the page shows them in full in the table. Anyone who can see your screen can read them.
Change the settings and write them to the sites
- In the section you want, change a Key or a Value, or click Add key for a new row.
- Untick Enabled to stop writing a key without deleting it.
- Click Remove to take a row off the list. Removing the last row of a section leaves an empty row in its place; an empty row is dropped when you save.
- Click the section's save button, such as Save Production.
Saving does two things straight away, without a confirmation: it stores the section's rows, and it writes the settings to every site in Matching sites. Saving All sites writes to every site.
- Keys are turned to capital letters. A row with no key is dropped.
- A key can appear only once per section. Otherwise you see Keys must be unique inside the selected environment. and nothing is saved.
- Some keys come already loaded in All sites. If you remove one, it comes back the next time you open the page; untick Enabled instead.
What happens to each site
For each enabled key, the site's environment file gets the line KEY=value: the line is added if it was missing, and its value replaced if it was there. Repeated lines for the same key are reduced to one. The rest of the file stays as it is. The file is then read back to check that every value landed.
When it finishes you see Ploi env defaults saved, and the section shows how many sites were Updated, Unchanged and Failed, with one line per site:
- updated with Env updated.
- unchanged with No changes needed.
- failed with Ploi accepted the env update but verification failed., or the error Ploi returned.
Last sync run # gives the number of the run. When you come back later, the section shows its Recent sync runs instead: the last five, with how many sites were updated and failed, the result and when it ran. The history keeps secret-looking values hidden.
Risks
- One save changes the environment file of every matching site, in every project, at once. A wrong value reaches all of them.
- There is no undo. To go back, put the old value in and save again.
- A site that failed may still have its old file or may have been changed without passing the check. Look at its message, and save again once the problem is fixed.
What it does not do
- It does not delete lines from the sites' files. Removing a row, or unticking Enabled, only stops writing that key; the line already in each file stays.
- It does not deploy or restart the sites.
- It does not touch applications without a Ploi identifier.
- It does not choose individual sites: a section always writes to all its matching sites.