DocsDeploy & operate

Environments and secrets

The same app in development, test, acceptance and production, its settings from .env files, the admin or the server’s environment, with secrets kept encrypted.

An app runs the same code everywhere and takes its settings from where it runs: an API key, an address, a feature switch. Each environment has its own values, secrets are kept encrypted, and the admin shows what is set, where it comes from, and what is missing. To pick the environment, name it when the server starts, with any name you like:

SLUURP_ENV=acc sluurp serve --public ./app
sluurp serve --public ./app --env test

By default, it’s development while developing and production otherwise.

Features include:

  • Values from .env files, the admin and the server’s environment, in a clear order
  • ctx.env in server code, and PUBLIC_ values in the browser
  • A check against .env.example that says what is missing or wrong
  • Secrets encrypted as ENC(…), safe to commit
  • A master key you can rotate

Where values come from

Each source wins over the one before:

SourceFor
.envEvery environment, committed with the app
.env.production (the environment’s name)That environment, committed
.env.local, .env.production.localThis machine only, never committed
Settings → Environment in the adminSet per environment, kept by the server
The server’s own environment variablesAlways win
.env.production
SITE_NAME=Shop
MAIL_FROM=hello@example.com
STRIPE_KEY=ENC(v1:4b9facb0:TcHnDVzphwM5XcKx0gEpoB8YBvXh34wFj062aOl7kfsMcPBRSBsY)

Read them

Server code reads them from ctx.env:

functions/checkout.ts
export default async function (ctx) {
  const stripe = ctx.env.STRIPE_KEY;
  if (ctx.env.ENVIRONMENT === "production") { /* … */ }
}
  • A value that isn’t set is undefined.
  • An app mounted beside another (--public shop=./shop) reads its own folder’s .env files; the admin’s values and the server’s environment are shared.
  • Only names starting with PUBLIC_ reach the browser, as import.meta.env.PUBLIC_SITE_NAME. Never give a secret that name.

What the app expects

.env.example lists every value the app needs, with a comment above each saying what it is, and required or secret where they apply:

.env.example
# The shop's name, shown in the header
SITE_NAME=My shop

# Stripe's secret key. required secret
STRIPE_KEY=sk_test_xxx

Settings → Environment checks each environment against it and says plainly what is wrong: a required value that isn’t set, a secret in plain text in a file, a PUBLIC_ value that looks like a secret, a value left as the example’s, or one that’s set but expected by nothing.

Encrypt secrets

Secrets are kept encrypted, written ENC(…), as Jasypt writes them. To encrypt a file, write each secret in it as DEC(…), and encrypt the file in place:

sluurp env encrypt .env.production

STRIPE_KEY=DEC(sk_live_…) becomes STRIPE_KEY=ENC(v1:4b9facb0:…), and the file can be committed. For one value:

sluurp env enc "sk_live_…"
sluurp env dec "ENC(v1:4b9facb0:…)"

A secret set in the admin is always kept encrypted, and is never shown whole again, only its last four characters.

Inside ENC(…), v1 is the cipher (AES-256-GCM, fixed by the version, never chosen by the value) and 4b9facb0 the key it was made with. A value made with another key says which one.

The master key

Give the key in the server’s environment, never beside what it protects:

SLUURP_MASTER_KEY="a long passphrase" sluurp serve --public ./app

Without it, a key is made in the data folder (master.key). That’s fine while developing, and the admin warns about it anywhere else.

Rotate the key

To change the key, start with the new key as SLUURP_MASTER_KEY and the old one as SLUURP_MASTER_KEY_OLD. Values made with either still open. Then encrypt everything again with the new key:

sluurp env rotate .env.production .env.acc

That covers the files given and every value kept in the admin. Then drop the old key.

View as Markdown