The complete quickstart guide to manage your secrets with dotenv-vault. Learn and understand how to use dotenv-vault with your application – in about 5 minutes.
In this guide, we’ll deploy an application with secrets to Heroku. We’ll create the app, load and sync its secrets, and deploy it using the .env.vault file. A quick skim over this tutorial, and you’ll understand all the foundational concepts of using dotenv-vault.
We’re using Heroku for this quickstart because it is the easiest to demo (in the least amount of your time), but any hosting platform will work.
🌱 Create our app
We’ll create a Node application for this guide, but you can follow along with your own application in any language or framework.
Set up the app’s containing folder.
$ mkdir hello-world
$ cd hello-world
Create the file that will house the code.
$ touch index.js
$ nano index.js
Write the code to build our hello-world web server. source
// index.js
const http = require('http')
const hostname = '127.0.0.1'
const port = 3000
const server = http.createServer((req, res) => {
res.statusCode = 200
res.setHeader('Content-Type', 'text/plain')
res.end('Hello World')
})
server.listen(port, hostname, () => {
console.log(`Server running at http://${hostname}:${port}/`)
})
Run our web server.
$ node index.js
Visit localhost:3000 and you will see “Hello World”.
Next, let’s use dotenv to customize the port and greeting.
🟨 Require dotenv
We’ll add dotenv to our app next, but if your app already has dotenv you can skip ahead to Sync .env file.
Install dotenv. source
# install locally (recommended)
$ npm install dotenv --save
Create a .env
file in the root of our project:
PORT="3000"
GREETING="Bonjour World"
Modify index.js to use require('dotenv').config()
and process.env
environment variables.
// index.js
require('dotenv').config()
const http = require('http')
const hostname = '127.0.0.1'
const port = process.env.PORT
const server = http.createServer((req, res) => {
res.statusCode = 200
res.setHeader('Content-Type', 'text/plain')
res.end(process.env.GREETING)
})
server.listen(port, hostname, () => {
console.log(`Server running at http://${hostname}:${port}/`)
})
Restart our web server.
$ node index.js
Now it says ‘Bonjour World’. Cool! We’re ready to backup and sync our .env
file.
🏆 Sync .env file
Once we have a .env file, we are ready to start syncing it with dotenv-vault. For this quickstart we’ll demonstrate doing this for ourselves, but you can also sync across your team and your other machines.
Usage is similar to git. Run the command:
$ npx dotenv-vault new
Follow those instructions and then run:
$ npx dotenv-vault login
Then run push and pull:
$ npx dotenv-vault push
$ npx dotenv-vault pull
That’s it! We synced our .env file.
🌴 Manage environments
After we pushed our .env file, we can manage our secrets across multiple environments. Let’s open the production environment to view and edit its environment variables. There is a fully built-in UI with dotenv-vault.
$ npx dotenv-vault open production
In the UI, we are going to delete the PORT
environment variable. We will rely on Heroku to fill that on deploy. We’ll edit the GREETING
environment variable to “Hello Production” so that we can recognize it on deploy.
🚀 Deploy .env.vault
Build our project’s encrypted .env.vault file. It securely encrypts our secrets in a cloud-agnostic payload.
🔒 Build encrypted .env.vault
$ npx dotenv-vault build
remote: Securely building .env.vault... done
We then commit that safely to code.
$ git add .env.vault
$ git commit -am "Build encrypted .env.vault file for deploy"
🔑 Set DOTENV_KEY
Let’s fetch the production decryption key - the DOTENV_KEY
.
$ npx dotenv-vault keys production
remote: Listing .env.vault decryption keys... done
dotenv://:[email protected]/vault/.env.vault?environment=production
Then let’s set the DOTENV_KEY
enviroment variable on Heroku.
$ heroku create
$ heroku config:set DOTENV_KEY='dotenv://:[email protected]/vault/.env.vault?environment=production'
🔐 Upgrade dotenv
We need to use the latest version of dotenv
so that we can decrypt the .env.vault payload on deploy. Install dotenv >= 16.1.0.
$ npm dotenv --save
// index.js
require('dotenv').config()
...
Also let’s edit our package.json
to have a start script so that Heroku can boot our application at runtime.
{
"scripts": {
"start": "node index.js"
},
"dependencies": {
"dotenv": "16.1.0"
}
}
🟣 Deploy to Heroku
We’re ready to deploy to heroku. Let’s do it.
$ git push heroku
When the deploy completes, we’ll see this line in the logs.
[[email protected]][INFO] Loading env from encrypted .env.vault
That’s it! The DOTENV_KEY
securely decrypts our .env.vault file at runtime and injects our secret environment variables – just in time.
This is safer than syncing our secrets to third-parties where they could leak. Plus we get a single source of truth. Make a change in the UI, run the build command, and redeploy. It’s that simple to manage your secrets with dotenv-vault.