Heroku

📘

These steps are for integrating a Heroku environment with the envkey-source integration tool. If you instead integrate with a language-specific wrapper, you won't need to do anything else to integrate with Heroku.

Connect a Heroku app

1.) Generate a server ENVKEY.

2.) Add the EnvKey buildpack at index 1--be sure to use the v3 branch to get the latest version:

$ heroku buildpacks:add --index 1 https://github.com/envkey/envkey-heroku-buildpack#v3

3.) Then add the buildpack that will run your application at index 2.

$ heroku buildpacks:add --index 2 heroku/nodejs

4.) Then set your ENVKEY from step 1 as a config var.

$ heroku config:set ENVKEY=...

5.) Now in your Procfile, wrap any processes you have defined with es -- proc-start-command

So if previously your Procfile looked like this:

web: node server.js

Change it to:

web: es -- node server.js

6.) And finally push a git update to trigger a re-build:

$ git push heroku master

Your Heroku server will now run with the latest EnvKey environment variables.

Updates and restarts

By default, you'll have run heroku restart to restart your dynos after an associated EnvKey environment is updated so your server picks up the latest values.

For automatic restarts, you can do the following:

1.) Install the Heroku CLI Buildpack at index 1:

heroku buildpacks:add heroku-community/cli --index 1

2.) Create a restart-dyno.sh in your project that looks like this:

heroku dyno:restart -a your-heroku-app-name $DYNO

Replace your-heroku-app-name above with the name of your Heroku app.

3.) Make your restart-dyno.sh file executable:

chmod +x restart-dyno.sh

4.) Generate a long-lived Heroku API key with this command:

heroku authorizations:create --short

5.) Create a HEROKU_API_KEY variable for the EnvKey environment associated with your Heroku app and set it to the API key you generated in the previous step.

6.) Change the prefix for your process start command in your Procfile to this:

web: es -r ./restart-dyno.sh --rolling -- node server.js

The --rolling flag, passed above to es, ensures that if you have multiple dynos, they will reload in batches in order to avoid downtime during restarts.

7.) Commit your changes, then push a git update to trigger a re-build:

git push heroku master

Now when your Heroku app's associated EnvKey environment is updated, all your dynos will be restarted with the latest variables.

Build phase variables

By default, your EnvKey variables won't be available to subsequent buildpacks during the build phase. You can make them available by setting the ENVKEY_BUILD_PHASE_EXPORT config var to any value:

heroku config:set ENVKEY_BUILD_PHASE_EXPORT=1

Then trigger a rebuild.

Warning: doing this can cause automatic restarts, as described in the previous section, not to work correctly. And even without using automatic restarts, you may need to trigger a full rebuild, rather than using just heroku restart for your apps to pick up the latest EnvKey values after an update.