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 testBy default, it’s development while developing and production otherwise.
Features include:
- Values from
.envfiles, the admin and the server’s environment, in a clear order ctx.envin server code, andPUBLIC_values in the browser- A check against
.env.examplethat 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:
| Source | For |
|---|---|
.env | Every environment, committed with the app |
.env.production (the environment’s name) | That environment, committed |
.env.local, .env.production.local | This machine only, never committed |
| Settings → Environment in the admin | Set per environment, kept by the server |
| The server’s own environment variables | Always win |
SITE_NAME=Shop
MAIL_FROM=hello@example.com
STRIPE_KEY=ENC(v1:4b9facb0:TcHnDVzphwM5XcKx0gEpoB8YBvXh34wFj062aOl7kfsMcPBRSBsY)Read them
Server code reads them from ctx.env:
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.envfiles; the admin’s values and the server’s environment are shared. - Only names starting with
PUBLIC_reach the browser, asimport.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:
# The shop's name, shown in the header
SITE_NAME=My shop
# Stripe's secret key. required secret
STRIPE_KEY=sk_test_xxxSettings → 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.productionSTRIPE_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 ./appWithout 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.accThat covers the files given and every value kept in the admin. Then drop the old key.