EJSON files are encrypted via a public-key cryptography scheme, the intention being that the non-secret public key can safely be stored on developer machines and in source control, whereas the sensitive private key can be scoped only to production infrastructure.
To generate an EJSON keypair, run
ejson keygen. The public key returned should be used in your project's
(by setting the
_public_key attribute on the top level object and running
Then, having set
EJSON_PRIVATE_KEY appropriately in your Heroku app's environment,
heroku-buildpack-ejson will be able to decrypt your
.ejson files on deploy.
The buildpack has a notion of environments, for instance to distinguish between
staging secret configuration.
The environment is controlled via the Heroku environment variable
EJSON_ENVIRONMENT is blank or unset, then by default the buildpack will attempt to decrypt all
.ejson files, excluding
those with a compound extensions specifying the environment (like
.production.ejson). For example, in this case
config/secrets.ejson would be decrypted on deploy into
would be left untouched.
EJSON_ENVIRONMENT is set, then the buildpack will exclusively decrypt files with a compound extension of the form
.$EJSON_ENVIRONMENT.ejson. For instance, suppose
would be decrypted into
be left untouched.
This scheme is intended to eliminate credential reuse. The intention is that each individual Heroku app is configured with
its own unique keypair; in particular, a
staging app and a
production app deployed from the same codebase should not
need to share.
Additionally, this strategy allows your app to be agnostic about its environment, with respect to configuration.
Suppose you commit a
secrets.json for development use, a
secrets.staging.ejson for a staging app,
secrets.production.ejson containing production credentials. Then, your app can read its configuration unconditionally
secrets.json; in development it will read the original development credentials, and in production or staging
secrets.json will have been overwritten with whichever credential set was appropriate.
Copy the snippet above into CLI.