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:
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 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.
Updated about 2 months ago