Getting Started

Installation

Install and configure the package using the following command :

node ace add @foadonis/crypt

Configure your Env schema

This step is done automatically when you first install Crypt.

In your start/env.ts file, import @foadonis/crypt to modify default Env behavior.

start/env.ts

import '@foadonis/crypt'
import { Env } from '@adonisjs/core/env'
 
export default await Env.create(new URL('../', import.meta.url), {
  [...]
})

Generate your keypair

Crypt works with asymmetric cryptography. It will generate two keys, one for encrypting (public key) and one for decrypting (public key).

Start generating a key for your development environment using the crypt:init command:

node ace crypt:init

Private key (decrypt)

This key is used to decrypt your environment variables. It is stored in a .env.keys file that MUST NOT be committed.

.env.keys

#/---------------------!CRYPT PRIVATE KEYS!-----------------------/
#/    private decryption keys. DO NOT commit to source control    /
#/     [how it works](https://friendsofadonis.com/docs/crypt)     /
#/----------------------------------------------------------------/
 
# .env
CRYPT_PRIVATE_KEY="14bfcf42753fffe8048af0db35cd4f6acabc15e378c246cd5fbf7cea519cf707"

Public key (encrypt)

This key is used to encrypt your environment variables. It is stored directly in your .env file and can be safely committed.

.env

#/---------------------[CRYPT PUBLIC KEY]-----------------------/
#/             public-key encryption for .env files             /
#/   [how it works](https://friendsofadonis.com/docs/crypt)     /
#/--------------------------------------------------------------/
CRYPT_PUBLIC_KEY="02caef368300cb9244d00b64deab85cd33c68b7e5e097b9ac73b0ba8125579f099"

As the public key can only be used to encrypt variables you can safely store it in your repository, allowing other members of your team to encrypt new variables without decrypting the existing ones.

Encrypt your first secret

Now that our schema is expecting an encrypted DB_PASSWORD and we have everything to encrypt and decrypt credentials, you can use the crypt:set command to encrypt your database password and store it in your .env file.

node ace crypt:set DB_PASSWORD mysuperpassword

This will add the encrypted credential in your .env file alongside unencrypted variables:

.env

#/---------------------[CRYPT PUBLIC KEY]-----------------------/
#/             public-key encryption for .env files             /
#/   [how it works](https://friendsofadonis.com/docs/crypt)     /
#/--------------------------------------------------------------/
CRYPT_PUBLIC_KEY="02caef368300cb9244d00b64deab85cd33c68b7e5e097b9ac73b0ba8125579f099"
 
DB_USER=adonis
DB_DATABASE=adonis
DB_PASSWORD="encrypted:BLkwNagdhoSpSAyRR1og..."

You can now start your Adonis application. During startup, Crypt will automatically decrypt your DB_PASSWORD using the private key (CRYPT_PRIVATE_KEY) stored in the .env.keys file.

Encrypt for production

Crypt select the environment variable file depending on your NODE_ENV. Each environment will have its own keypair named CRYPT_PRIVATE_KEY_<environment>/CRYPT_PUBLIC_KEY_<environment>.

# Encrypt the secret in `.env.production`
node ace encrypt:set DB_PASSWORD myproductionpassword --env production
 
# or using NODE_ENV
NODE_ENV=production node ace encrypt:set DB_PASSWORD mystagingpassword

Update Gitignore

Now that you are allowed to commit your dotenv files lets update the .gitignore:

.gitignore

.env
.env.*.local
.env.keys

See steps performed by this command

On this page