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.
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.
You can migrate on a gradual basis over time--you don't need to re-invite all users and regenerate all server ENVKEYs in one go.
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.
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
If you have a large v1 organization, you don't need to re-invite all your users and set all your new ENVKEYs all at once. You can re-invite users and update server ENVKEYs gradually over time as you're ready. Though all users will be re-invited and all server ENVKEYs re-generated when you finish the export/import steps described above, you don't need to send users Encryption Tokens or update ENVKEYs immediately.
Instead, you can just send Encryption Tokens to the users you want to invite now, and ignore the rest of the re-generated invitations, allowing them to expire. Later, you can re-invite additional users to v2 as needed.
Similarly for server ENVKEYs, you can update update as many as you want immediately, and save the rest to be updated later. Just ignore any re-generated server ENVKEYs that you don't want to update yet. Later, when you're ready to update a server ENVKEY to v2, you can go to the app in the EnvKey v2 UI, go to the
ENVKEYstab, find your server, and clickRegenerate, then update the ENVKEY on your server at that point.
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:
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):
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:
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-v2instead ofenvkey-sourcein order to avoid overwriting the v1 binary and breaking any of your v1-based workflows. You can also use theesalias, which be installed as long as it isn't currently in your$PATHfor 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 excecute 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 January 2023, at which point we’ll retire the v1 service so that we can concentrate our efforts on the v2 (and beyond).
Updated 5 months ago