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.


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.


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:
Updated 3 months ago