---
title: Environments and secrets
description: 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.
section: Deploy & operate
order: 3
---

# 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:

```sh title="Terminal"
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:

| 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 |

```sh title=".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`:

```ts title="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:

```sh title=".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:

```sh title="Terminal"
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:

```sh title="Terminal"
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:

```sh title="Terminal"
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:

```sh title="Terminal"
sluurp env rotate .env.production .env.acc
```

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