Use dotenvx with Railway

Use dotenvx with Railway

Initial setup

Install the necessary web server libraries in the language of your choice.

npm install express --save

Create a simple Hello World program.

// index.js
const express = require('express')
const app = express()
const PORT = process.env.PORT || 3000

app.get('/', (req, res) => {
  res.send(`Hello ${process.env.HELLO || ''}`)

app.listen(PORT, () => {
  console.log(`Server running on port:${PORT}`)

Create Dockerfile.

# Dockerfile
FROM node:20
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "index.js"]

Create .dockerignore.


# .dockerignore

Commit to code and push to Railway.

npx @railway/cli@latest init
npx @railway/cli@latest up
npx @railway/cli@latest domain

Railway also requires you set the correct PORT environment variable for your app.
# set PORT to 3000

Redeploy to Railway.

npx @railway/cli@latest up

Once deployed, your app will say 'Hello [blank]' as it doesn't have a way to access the environment variable yet. Let's do that next.

Run dotenvx

Install dotenvx.

# install with Homebrew and then use the dotenvx command
brew install dotenvx/brew/dotenvx
dotenvx help

Create a .env file in the root of your project.


# .env

Inject your env using dotenvx.

dotenvx run -- node index.js

Your app will say Hello World. The values from your .env file were successfully injected into your env. That covers local development. Let's solve for production next.

Add production environment

Create a .env.production file in the root of your project.


# .env.production

Use dotenvx to load your .env.production file.

dotenvx run --env-file=.env.production -- node index.js

Your app will say Hello production, simulating production. Solid. Let's encrypt your secrets next.

Encrypt secrets

Use dotenvx to encrypt your secrets.

dotenvx encrypt

This generates a .env.vault and .env.keys file.


#/         cloud-agnostic vaulting standard         /
#/   [how it works](   /

# development

# production

The .env.vault file contains encrypted (AES-256-GCM) versions of your secrets, and the .env.keys file contains the decryption keys.


#/   DOTENV_KEYs. DO NOT commit to source control   /
#/   [how it works](    /

We're ready to add dotenvx to Railway.

Add dotenvx to Dockerfile

Install dotenvx to your Dockerfile and prepend your app command with dotenvx run --.

# Dockerfile
FROM node:20

# Install dotenvx
RUN curl -fsS | sh

COPY package*.json ./
RUN npm install
COPY . .

# Prepend dotenvx run
CMD ["dotenvx", "run", "--", "node", "index.js"]

Redeploy to Railway.

npx @railway/cli@latest up
$ npx @railway/cli@latest logs
[[email protected]] missing .env file (/app/.env)
? in development: add one with [echo "HELLO=World" > .env] and re-run [dotenvx run -- node index.js]
? for production: set [DOTENV_KEY] on your server and re-deploy
Server running on port:7136

The logs tell us missing .env file. This is expected, as we don't want to commit .env to code. It also tells us, for production, that we should set DOTENV_KEY. That is what we want to do. Let's do that next.


Set DOTENV_KEY on Railway using the production key in your .env.keys file.


npx @railway/cli@latest up

Your app reboots and env is successfully injected using the encrypted contents of .env.vault.

$ npx @railway/cli@latest logs
[[email protected]] injecting env (1) from encrypted .env.vault
Server running on port:5821

Visit your url and it says Hello production.

Great job! That's pretty much it. See the bonus section(s) below to go a little deeper.


Try changing the value of .env.production to your name.


# .env.production

Re-encrypt it.

dotenvx encrypt

Commit .env.vault safely to code and redeploy.

git commit -am "update production secret"
npx @railway/cli@latest up