Skip to content
Guides & References

Keep .env and APP_KEY in step on rConfig HA nodes

Why both rConfig HA nodes need an identical .env and APP_KEY, what lives there and what lives in the database, and how to keep the two copies in step.

High AvailabilityUpdated
On this page

Keep .env and APP_KEY in step on rConfig HA nodes

Every other component in a highly available rConfig is shared or replicated: the database, Redis or Valkey, storage. .env is the exception. Each node reads its own local copy, and nothing copies it for you. If the passive node’s copy is out of date when it takes over, failover can look successful and still break every backup. This page covers what’s in .env, why it must be identical, and how to keep it that way.

Figure HA-1: the building blocks of rConfig HA, with the keys lane at the bottom showing .env and APP_KEY identical on Node A and Node B
Figure HA-1: The building blocks of rConfig HA. The bottom lane is the one layer nothing replicates for you: .env and APP_KEY must be identical on both nodes. Click the diagram to open the interactive version.

What’s in .env

The file is /var/www/html/rconfig8/current/.env. For HA, the settings fall into four groups:

Group Examples Why it matters on failover
The encryption key APP_KEY Encrypts every device credential, and configs when configuration encryption is on. A different key on the passive node can’t decrypt any of them, so every backup fails
Where the data is DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD, REDIS_HOST, REDIS_PASSWORD Must point at the database and Redis or Valkey VIPs, with the same credentials, or the passive node can’t reach the data
How rConfig is reached APP_URL Should be the VIP’s DNS name, so links in emails, webhooks and notifications work from either node
Behaviour HORIZON_MAX_PROCESS, SCRIPT_FEATURE_ENABLED, MASK_DEVICE_CREDENTIALS, mail settings, configuration obfuscation settings A difference changes how rConfig behaves after failover, for example scripts stop running because the Script Integration Engine is off

The rule: both nodes have the same .env, byte for byte. There are no node-specific values in a correct HA design: every address in it is a VIP, not a node’s own address.


What isn’t in .env

More settings live in the database each release, and those follow the database automatically. For example, key vault settings moved into the database in V8.4.2 and the Config Hard Link setting in V8.4.3. When a setting moves into the UI, check the release notes: rConfig often keeps reading the old .env value until the setting is saved in the UI, so both nodes still need the same .env until then.


Keeping the copies in step

Pick one way and use it for every change.

Method How Fits
Configuration management (Ansible, Puppet, Salt) The .env is a template or vaulted file in your configuration repository, pushed to both nodes Teams that already manage servers this way. The best option: changes are reviewed and both nodes always get the same file
Copy after every change Edit on the active node, then copy to the passive node over SSH, keeping owner and mode Smaller teams. Simple, but depends on someone remembering every time

Copying by hand, as root on the active node:

Terminal window
ENV=/var/www/html/rconfig8/current/.env
rsync -a --chmod=F600 "$ENV" root@rconfig-b.example.com:"$ENV"
ssh root@rconfig-b.example.com "chown apache:apache $ENV" # www-data on Ubuntu

Don’t keep .env on the shared storage to avoid copying it. If that storage is unavailable, neither node can start, and you’ve turned one failure into two.

After every change

On whichever node runs rConfig at the time (the active node), apply the change:

Terminal window
cd /var/www/html/rconfig8/current
php artisan rconfig:clear-all # pick up the new values
php artisan horizon:terminate # Supervisor restarts the workers with the new values

The passive node has nothing running, so it reads the new file when it next starts its services, on failover.

Check they match

Compare checksums on both nodes after every change, after every upgrade, and before every failover test:

Terminal window
sha256sum /var/www/html/rconfig8/current/.env

The two values must be identical. Add the same check to your monitoring, so a drift is caught before a failover finds it.


APP_KEY in particular

  • Never generate a key on the passive node. A fresh install creates a new APP_KEY. Build the passive node, then replace its .env with the active node’s before it ever connects to the shared database.
  • Never rotate the key on one node. Rotation re-encrypts data and must only be done with rConfig support. See System Encryption Key. After a rotation, copy the new .env to the passive node straight away.
  • Back up .env with the database. A database backup without the matching APP_KEY can’t decrypt any device credential. See Backups.

Upgrades

Upgrade both nodes in the same maintenance window. Updates can add or change values in .env: for example, from V8.4.1 the deploy script sets REDIS_PASSWORD if .env has none. After upgrading both nodes, compare the checksums, and copy the active node’s .env to the passive node if they differ.


Type to search.