Flisk Secrets

---
name: flisk-secrets
description: Give Flisk services their configuration and secrets - non-secret `params` in service.json, secret names under `secrets.required` / `secrets.optional` with the values in the gitignored project `.env`, `JWT_SECRET` and `DB_PASSWORD`, another env file for one run with `flisk up --env-file`, and Infisical via FLISK_SECRET_PROVIDER. Use when a service needs an API key or environment variable, Compose refuses to start because a variable is missing, or a value does not reach the container. For host ports, see flisk-ports.
license: MIT
compatibility: Requires the flisk CLI. Does not deploy.
metadata:
  author: flisk-sh
  version: "1.0"
---

# Environment, params and secrets

| What | Where you write it | Committed? |
| --- | --- | --- |
| Non-secret config | `params` in `service.json` | Yes |
| A secret's name | `secrets` in `service.json` | Yes |
| A secret's value, `DB_PASSWORD`, `JWT_SECRET` | the project `.env` | No (gitignored) |

## Workflow

1. Non-secret value: add it to `params` in the service's `service.json`:
   ```json
   { "params": { "API_BASE_URL": "http://localhost", "GREETING": "hello world" } }
   ```
   Flisk writes it to the generated `.autogenerated/.env.<type>.autogenerated`. `envVars` is the deprecated name.
2. Secret: name it in `service.json` and put the value in `.env`:
   ```json
   { "secrets": { "required": ["STRIPE_KEY"], "optional": ["SENTRY_DSN"] } }
   ```
   A missing required secret makes Compose refuse to start the resource and name the variable; an optional one arrives empty.
3. Run `flisk doctor`: it reports missing or empty keys in `.env` and a `DATABASE_URL` whose password differs from `DB_PASSWORD`.
4. Restart the stack with `flisk up` so the containers pick the values up.

## Good to know

- `flisk project` creates `.env` with a generated `DB_PASSWORD` and `JWT_SECRET`; `flisk up` adds keys a newer CLI needs and never changes an existing value.
- `flisk up --env-file .env.integration` uses that file instead of `.env` for one run. It must be inside the project and carry `TILT_ENV`, `DB_PASSWORD` and `JWT_SECRET` (copy `.env` to start one).
- The Postgres volume keeps the password it was created with; changing `DB_PASSWORD` later does not change the database password.
- `FLISK_SECRET_PROVIDER=infisical` leaves secrets to Infisical; nothing is injected from `.env`.
- `jwtSecret` in `service.json` is ignored; set `JWT_SECRET` in `.env`.

## Guardrails

- Never commit real secrets, `.env` files or license keys, and never print secret values.
- `.flisk/.project-id` is local machine state; make sure the project's `.gitignore` covers it.
- Do not edit the generated env files; change `params` or `.env`.
- Guide: [docs/environment.md](https://github.com/flisk-sh/flisk/blob/main/docs/environment.md).