Railway Environment Variables

Your app needs some private info to work. Database passwords, API keys, secret tokens, that kind of stuff. None of it should EVER be typed straight into your code. It lives in environment variables instead.

What Are Environment Variables?#

Environment variables are settings that live outside your code. They fill in the blanks for your app. Your code says "connect to the database at _____" and the environment variable fills in that blank.

Think of a form letter.

Dear ___NAME___,
 
Your order ___ORDER_NUMBER___ has shipped!

The letter is the same for everybody, but the blanks get filled in differently for each person. Environment variables do the exact same thing for your app.

Why Not Put Secrets in Code?#

You might be wondering why you can't just type the password right into the code. Here's why that's dangerous.

1. Code Gets Shared#

When you push to GitHub, your code might be public. Or you might share it with teammates. Anybody who sees the code sees your secrets too.

2. Different Environments Need Different Values#

Your local development database has one password, and your production database has another. You don't want to edit your code every time you switch.

3. Security Best Practice#

Security folks all agree on this one. Secrets stay separate from code. If someone breaks into your GitHub, they shouldn't get your database password as a bonus prize.

Types of Secrets#

So what counts as a secret? Anything you wouldn't want a stranger to see.

• Database passwords. Access to your data
• API keys. Access to third-party services (Stripe, SendGrid, etc.)
• JWT secrets. Used to sign authentication tokens
• Encryption keys. Used to encrypt sensitive data
• OAuth credentials. Client IDs and secrets for login systems

If it would cause damage in the wrong hands, it's a secret.

Setting Environment Variables in Railway#

Railway keeps this part simple.

Step 1. Open Your Service#

In your Railway project, click the service (your app) you want to set up.

Step 2. Go to Variables Tab#

Click the "Variables" tab. Any variables you already have will be listed here.

Step 3. Add a Variable#

Click "New Variable" or "+ Add." You'll see two fields.

• Name. The variable name (like DATABASE_URL)
• Value. The actual value (like the connection string)

Step 4. Enter Your Variable#

Type in the name and the value, then click "Add" to save.

Step 5. Repeat for Other Variables#

Add whatever other environment variables your app needs.

After you add or change variables, Railway doesn't apply them right away. It stages them as changes, and you'll see a banner on your project canvas. Click "Deploy" on that banner and Railway redeploys your app with the new values. (Forget this step and you'll be scratching your head wondering why nothing changed.)

Common Environment Variables#

Here are the ones you'll run into a lot.

DATABASE_URL#

The connection string for your database. Railway can set this for you when you add a database.

NODE_ENV#

Tells Node.js apps whether they're in development or production.

NODE_ENV=production

PORT#

The network port your app should listen on. Railway sets this one automatically.

API Keys#

Credentials for third-party services.

STRIPE_SECRET_KEY=sk_live_...
SENDGRID_API_KEY=SG...

App Secrets#

Secret values that belong to your own app.

JWT_SECRET=a-very-long-random-string
SESSION_SECRET=another-random-string

Using Environment Variables in Code#

Here's how you grab environment variables in a few different languages.

JavaScript/Node.js#

const apiKey = process.env.STRIPE_SECRET_KEY;
const dbUrl = process.env.DATABASE_URL;

Python#

import os
api_key = os.environ.get('STRIPE_SECRET_KEY')
db_url = os.environ.get('DATABASE_URL')

Next.js (Special Rules)#

In Next.js, any variable the browser needs to see has to start with NEXT_PUBLIC_.

NEXT_PUBLIC_API_URL=https://api.example.com

Variables without that prefix only exist on the server (which is usually exactly what you want for secrets).

Reference Variables in Railway#

Railway has a really handy feature called reference variables. They let one service pull values from another service automatically.

So your app can grab your database's connection string without any copying and pasting. Here's how.

Step 1. Add a Variable#

In your app's Variables tab, click to add a new variable.

Step 2. Use Reference Syntax#

Instead of typing a regular value, you point at another service.

DATABASE_URL=${{Postgres.DATABASE_URL}}

That tells Railway to pull the value from your Postgres service.

Step 3. Save#

Railway keeps this variable in sync for you. If your database URL changes, your app picks up the new value automatically.

Local Development#

When you're working on your own computer, you need environment variables too. The usual move is a .env file.

Create a .env File#

In your project folder, make a file named .env.

DATABASE_URL=postgresql://localhost:5432/myapp
STRIPE_SECRET_KEY=sk_test_abc123

Load the File#

Use a library like dotenv (for Node.js) to load those variables. Install it first.

npm install dotenv

Then load it at the very top of your app's main file.

require('dotenv').config();
// Now process.env.DATABASE_URL is available

Keep .env Out of Git#

Add .env to your .gitignore file.

# .gitignore
.env

That way you can't accidentally push your secrets to GitHub.

Best Practices#

A few habits worth building now.

Use a .env.example File#

Make a file that lists which variables are needed, minus the real values.

# .env.example
DATABASE_URL=
STRIPE_SECRET_KEY=
JWT_SECRET=

That way other developers know exactly what they need to set up.

Use Strong, Random Secrets#

For stuff like JWT_SECRET, use long random strings. Online generators can help.

Rotate Secrets Periodically#

Change your important secrets every few months. If one ever leaks, that limits the damage.

Different Values for Different Environments#

Use different API keys and passwords for development and production. If your dev key leaks, production is still safe and sound.

TL;DR#

• Environment variables store configuration outside your code
• Never put secrets like passwords and API keys straight into code
• Railway's Variables tab makes setting env vars easy
• Use .env files for local development (but never commit them!)
• Reference variables let Railway services share configuration automatically
• Variables starting with NEXT_PUBLIC_ are exposed to the browser in Next.js

What's Next?#

Your app is deployed, it has a database, and it's set up with environment variables. It's still sitting on a Railway-generated URL though. Next lesson, you'll connect your own domain name so it looks legit.