dotenv-vault

Committing .env.vault

DO commit your .env.vault file to your code repository. It contains AES-256 encrypted ciphertext and is safe to store. DO NOT commit your .env files.

Handling a leaked DOTENV_KEY

If your DOTENV_KEY is leaked:

1. If the attacker does not have your .env.vault file: No immediate action is required, as they need both to access secrets.
2. If the attacker does have your .env.vault file:
   • Immediately rotate secrets at your third-party providers.
   • Rotate your DOTENV_KEY using the rotatekey command.
   • Rebuild your .env.vault file.
   • Redeploy.

dotenv-vault automatically sets up multiple environments (like staging, production, etc.) after you push your .env file.

• UI Management: Open the included UI to manage secrets for specific environments using npx dotenv-vault@latest open <environment_name>.
• Pulling specific environments: To pull the .env file for a specific environment to your local machine, use npx dotenv-vault@latest pull <environment_name>.

npx dotenv-vault@latest open production

npx dotenv-vault@latest pull production

dotenv-vault provides integration guides for a wide variety of platforms, CI/CD tools, frameworks, and languages. You can find specific instructions for setting up environment variable synchronization with services like Vercel, Heroku, GitHub Actions, Docker, AWS Lambda, and many others.

Common categories include:

• Platforms: Vercel, Heroku, Netlify, Fly.io, Digital Ocean, etc.
• CI/CD: GitHub Actions, GitLab CI/CD, CircleCI, Travis CI, Google Cloud Build.
• Frameworks: Express, NextJS, Remix, Astro, Rails, Nuxt, Vite, etc.
• Languages: Node.js, Ruby, Python, etc.
• Infrastructure/Tools: Docker, Docker Compose, Pulumi, Supabase.

Instead of managing production secrets in third-party tools, use an encrypted .env.vault file.

Workflow:

1. Build the vault: Generate the encrypted file using npx dotenv-vault@latest build.
2. Get the decryption key: Retrieve the production DOTENV_KEY using npx dotenv-vault@latest keys production.
3. Configure your server: Set the DOTENV_KEY environment variable on your production server (e.g., via Heroku).
4. Deploy: Commit .env.vault to your repository and deploy. The secrets will be decrypted and injected as environment variables at runtime.

npx dotenv-vault@latest build
npx dotenv-vault@latest keys production

# Example for Heroku
heroku config:set DOTENV_KEY=dotenv://:key_1234…@dotenv.org/vault/.env.vault?environment=production

git add .env.vault
git commit -am "Update .env.vault"
git push

To quickly sync your .env file to the cloud, run the push command. This securely uploads your local .env and builds a .env.vault file.

To sync changes from the cloud to your local machine, run the pull command.

npx dotenv-vault@latest push

npx dotenv-vault@latest pull

The recommended workflow for sharing environment variables with a team is:

1. Push changes: When you modify your .env file, run npx dotenv-vault@latest push.
2. Commit the vault: Safely commit the generated .env.vault file to your version control system (e.g., Git).
3. Teammate pulls: Your teammate pulls the latest code from Git and then runs npx dotenv-vault@latest pull to sync their local .env file with the latest secrets.

npx dotenv-vault@latest push

git add .env.vault
git commit -am "Add .env.vault"
git push

git pull
npx dotenv-vault@latest pull

When you run the pull command to sync remote environment variables to your local machine, dotenv-vault performs an automatic backup of your existing environment files to prevent data loss.

If a local file already exists with the name of the environment being pulled (or the custom filename provided via the CLI), the service renames the existing file by appending .previous to its name before writing the new data.

Example workflow:

1. You have a local .env.production.
2. You run dotenv vault pull for the production environment.
3. The existing .env.production is renamed to .env.production.previous.
4. The new data is written to .env.production.
5. If the pull includes vault data, .env.vault is also updated.

The project uses a specific file to store encrypted vault data. Depending on the project version, the filename and the environment variable key used to access the vault value may differ:

• Modern projects: Use .env.vault as the filename and DOTENV_VAULT as the key.
• Legacy projects: Use .env.project as the filename and DOTENV_PROJECT as the key.

If .env.vault is not decrypting successfully, follow these steps:

1. Check Library Version: Ensure you are using dotenv@16.1.0 or greater.
2. Test Local Decryption: Run the decrypt command manually to see if it outputs environment variables:

   $ npx dotenv-vault@latest decrypt dotenv://:key_1234..@dotenv.local/vault/.env.vault?environment=production

3. Test Decryption on Boot: Verify that your application can boot using the DOTENV_KEY directly:

   $ DOTENV_KEY='dotenv://:key_1234..@dotenv.local/vault/.env.vault?environment=production' npm start

The dotenv-vault CLI and its connection to the vault service can be configured using environment variables. These variables follow a specific precedence: they are read from the current process environment first, then from the settings defined within your .env.vault file, and finally fall back to default values if neither is present.

• DOTENV_CLI: Specifies the command used to run the CLI. Defaults to npx dotenv-vault@latest.
• DOTENV_API_URL: Specifies the API endpoint for the vault service. Defaults to https://vault.dotenv.org.

When using dotenv-vault, the DOTENV_KEY must be a valid URI that provides the decryption key, the target environment, and allows the service to locate the ciphertext in your .env.vault file. If you encounter errors during decryption, ensure your DOTENV_KEY follows this structure:

dotenv://<key>@<environment>?environment=<environment>

Common error causes:

• INVALID_DOTENV_KEY: Missing key part: The password component of the URI is missing.
• INVALID_DOTENV_KEY: Missing environment part: The environment search parameter is missing from the URI.
• NOT_FOUND_DOTENV_ENVIRONMENT: The environment specified in the URI (e.g., production) does not have a corresponding encrypted payload in your .env.vault file (e.g., DOTENV_VAULT_PRODUCTION). To fix this, run the build command to include the missing environment in your vault file.

If the pull operation fails, dotenv-vault will attempt to provide specific error details. Errors typically fall under the PULL_ERROR code, but the service may surface more specific error codes and suggestions returned from the remote server.

When an error occurs, look for:

• Error Message: A description of what went wrong (e.g., authentication issues or missing vault data).
• Error Code: A specific machine-readable code (e.g., if the server provides one).
• Suggestions: Actionable steps provided by the server to resolve the issue (e.g., instructions to run login again).