Migrating From V1

You can migrate all your users, apps, variables, and server ENVKEYs from v1 into a new v2 organization. You must be an Org Owner in the v1 organization you're exporting from.

Export Archive From V1

Open up the EnvKey V1 App and sign in. Open up the sidebar settings menu (click the ⚙️ icon), and then click My Organization. Look for the Export Archive For V2 section near the bottom of the settings form, then click the Export Archive button and choose a location for the .envkey-archive file. When the export completes, an Encryption Key will be shown in an alert dialog. Copy this--you'll need it when importing the archive into v2. On Windows, you won't be able to select the text, but if you press Ctrl + C while the dialog is active, it will copy the alert text.

Import Archive Into V2

First, install EnvKey v2 and create a fresh organization to import into. Then open up the EnvKey UI. Click the Org, account, and device settings menu with your organization's name in it at the top-left of the screen. From there, click My Org. Then click on the Import/Export tab, and then the Import Org button. Select the .envkey-archive file you want to import, enter the Encryption Key you copied in the previous step, then start the import.


v2 Encryption Improvements

One of EnvKey v2's key improvements is switching to a faster and more secure encryption library (NaCl instead of OpenPGP), as well as implementing much faster algorithms for verification and encryption/decryption operations.

Because of these changes, new encryption keys must be generated for users and ENVKEYs. Unfortunately, this means that a v1 org can't just be seamlessly moved over to v2 without any action on your part.

While apps, environments, config data, users, and servers can be transferred automatically, you'll have to send a new Encryption Token out-of-band to each re-invited user, and they'll have to accept an invite to your v2 organization. Server ENVKEYs will also need to be re-generated and updated wherever you're using them to complete the migration. Local development ENVKEYs are no longer required in EnvKey v2.

Send Encryption Tokens For Invitations

When the import completes, you'll see a list of all the people from your v1 organization that have been re-invited. They'll receive Invite Tokens by email. You'll also need to send each one of them an Encryption Token.

Update Server ENVKEYs

You'll also see a list of all the server ENVKEYs from your v1 organization that have been re-generated. You'll need to update these wherever you're currently using a server ENVKEY.


Automatic Upgrade

The EnvKey team is now working on automatic upgrade functionality that won't require you to regenerate ENVKEYs or re-invite users. Please see this announcement for more details.

Initialize Apps For Local Development

In a terminal, cd into each directory you're using EnvKey with, and run envkey init. Make sure the generated .envkey file is checked in to version control.

Now all of your developers can load the latest environment in each app they're granted access to without needing to generate Local Development ENVKEYs.


Importing Gradually

By selecting which users and apps to import from an archive, you can import on a gradual basis over time.

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 available for these languages:

envkey-node v2

envkey-python v2

envkey-ruby v2

envkeygo v2

A library is also available to simplify integration with webpack if you need to make some configuration available to a client-side application (it can also be used as an example for integrating with other bundlers--the code is very simple):

envkey-webpack v2

Pinning v1 versions

If you're continuing to use v1 with envkey-node, envkey-ruby, envkey-python, and/or envkey-webpack, make sure you pin the existing packages to version 1 wherever you're installing them so that you don't accidentally upgrade to v2, which won't work with ENVKEYs generated in v1. Instructions for doing so can be found in the v1 repos for each library:

envkey-node v1

envkey-python v1

envkey-ruby v1

envkey-webpack v1

Integration: using envkey-source


envkey-source v1 → v2

Note that if you already have envkey-source v1 installed locally when you install EnvKey v2 and start the EnvKey UI, envkey-source will be installed as envkey-source-v2 instead of envkey-source in order to avoid overwriting the v1 binary and breaking any of your v1-based workflows. You can also use the es alias, which be installed as long as it isn't currently in your $PATH for some other purpose. Please adapt the examples below accordingly.

If you decide to switch to envkey-source, or you're already using it but would like to update your usage to take advantage of additional v2 functionality, do the following:

1.) Replace whatever command you're using to start your app in development with the following:

envkey-source -wc -- command
# the -w flag will automatically exit and re-run your command your command when the environment changes
# the -c flag will maintain an encrypted backup on the local filesystem so you can keep working offline if you lose your internet connection

es -wc -- command
# use the es alias to type less

2.) Install envkey-source on your servers

3.) On a server, do the same as you did on development for your start command(s).

4.) If it fits your ops approach, you can run a separate command when the environment changes instead of using -w for automatic reloads:

es -r reload-command -c -- command

Or simply execute your command with the latest environment and handle reloads manually (like in v1):

es -- command

You might also want to run a watcher elsewhere that executes a command only when the environment changes (and doesn't execute any command initially):

es -r ./restart-infra

V1 Sunset

Now that EnvKey v2 is live, we encourage our v1 customers to migrate so they can take advantage of all the v2 has to offer. Of course, we understand that this may take time. So we’ll continue running EnvKey v1 until the end of March 2023.

After that point, any organizations that are still on v1 and haven't yet upgraded will be subscribed to a v2 plan (see v2 pricing here). Users will still be able to sign in to EnvKey v1, and v1 ENVKEYs will continue to work, but no further actions will be permitted until the organization owner upgrades to v2.