Integration Quickstart

Create or initialize an app

When you create a new app in EnvKey, you'll be asked for the corresponding project's root directory so that a .envkey config file can be created there. This file is not sensitive and should be checked in to version control.

If you need to create a .envkey file for an existing app, navigate to the corresponding project's root directory in a terminal and execute envkey init.

Connect a development machine

If you run your dev environment on Docker or a remote VM, go to connecting with local development ENVKEYs.

To connect to an EnvKey app's development environment on a development machine, first make sure the EnvKey App and CLI are installed, that you're signed in to your EnvKey organization, and that your project's root directory has a .envkey file in it .

By installing the EnvKey App and CLI, the envkey-source tool was also installed, and that's what you'll use to integrate.

Just replace whatever command you use to start your app in development mode with the following:

$ envkey-source -wc -- start-app-command

You can use the es alias to type a bit less and spare those wrists:

$ es -wc -- start-app-command

That will start your app with all your EnvKey environment variables set. It will also automatically restart your app whenever the environment changes thanks to the -w flag. The -c flag will maintain an encrypted cache in the file system, allowing you to keep working offline if you lose your internet connection.

If automatically restarting doesn't work for your use case, you can either leave off the -w and restart manually, or you can implement custom reload logic:

$ es -r ./reload-env -c -- start-app-command

Connect servers

1.) First, generate a server ENVKEY.

Open up the EnvKey App, sign in, select the application you want to integrate with in the sidebar, and then select the ENVKEYs tab. Assuming you have permission to manage servers, you'll see a Server Keys section at the top. Click the Generate Server Key button, then copy the generated ENVKEY.

Screen Shot 2022-02-26 at 10.50.55 PM.png

Or you can use the EnvKey CLI:

envkey servers create

If you're connecting a server using Docker, go to the Docker integration guide.
If you're connecting a server using Heroku , go to the Heroku guide.
If you're connecting a server using Kubernetes , go to the Kubernetes guide.

Otherwise:

2.) Run the following on your server to install envkey-source:

VERSION=$(curl https://envkey-releases.s3.amazonaws.com/latest/envkeysource-version.txt) && curl -s https://envkey-releases.s3.amazonaws.com/envkeysource/release_artifacts/$VERSION/install.sh | bash

For more installation options, including instructions for verifying the envkey-source binary, check out the envkey-source docs.

3.) Now set your ENVKEY as an environment variable on your server or paste it into a .env file in your home directory like this:

$ echo ENVKEY=PASTE_IN_YOUR_ENVKEY > ~/.env

4.) Now replace whatever command you use to start your app on the server with the following:

$ es -w --rolling -- start-app-command

That will start your app with all your EnvKey environment variables set. It will also automatically restart your app whenever the environment changes thanks to the -w flag.

Thanks to the --rolling flag, envkey-source will perform a rolling reload across all connected processes when there's a change so you can avoid downtime. By default, rolling reloads run in up to four batches, with a 5 second delay between batches. You can use the --rolling-pct flag to change the number of batches, and the --throttle flag to change the delay. If your app takes longer than 5 seconds to initialize, be sure to increase the --throttle accordingly.

If automatically restarting doesn't work for your use case, you can either leave off the -w and the --rolling flags and restart manually, or you can implement custom reload logic with the -r flag.

Connecting with local development ENVKEYs (optional)

In some situations, like when you're using containers in development or developing on a remote VM, it might not be practical to install the EnvKey App and CLI on the OS running your program. In that case, you can generate a local development ENVKEY instead and use that to connect to your development environment.

1.) Open up the EnvKey App, sign in, select the application you want to integrate with in the sidebar, and then select the ENVKEYs tab. Assuming you have permission to manage servers, you'll see a Local Keys section at the top. Click the Generate Local Key button, then copy the generated ENVKEY.

Screen Shot 2022-02-26 at 5.06.58 PM.png

Or you can use the EnvKey CLI:

envkey local-keys create

If you're connecting a local development ENVKEY with Docker, go to the Docker integration guide.

Otherwise:

2.) Run the following in your container or VM to install envkey-source:

VERSION=$(curl https://envkey-releases.s3.amazonaws.com/latest/envkeysource-version.txt) && curl -s https://envkey-releases.s3.amazonaws.com/envkeysource/release_artifacts/$VERSION/install.sh | bash

For more installation options, including instructions for verifying the envkey-source binary, check out the envkey-source docs.

3.) Now either:

Copy your ENVKEY into a file at: $HOME/.envkey/apps/$APP_ID.env ($APP_ID will be replaced with your app's id: look for it in the UI or CLI output after generating a local key).
Copy your ENVKEY into a .env file in the home directory: $HOME/.env
Set your ENVKEY as an environment variable that will be visible to your app.

4.) Then start your app:

$ es -wc -- start-app-command

More on envkey-source

Check out the envkey-source docs for more details on the options available when using envkey-source. You can overwrite specific variables, detect which specific variables have changed when there's an update, and more.

Language libraries for Node, Python, Go, and Ruby/Rails

In EnvKey v2, envkey-source is the recommended integration tool. It weighs in at a small fraction of the size of the language-specific libraries while offering additional functionality and better performance.

That said, to allow for a smooth transition from v1 and handle platforms where it's difficult to install envkey-source, officially supported libraries are still available for these languages: