serverpod-configuration

# Serverpod Configuration Priority (highest wins): **Dart config object** > **environment variables** > **YAML config files**. The config uses YAML files that live in `config/`. Secrets are in `config/passwords.yaml` or env vars with `SERVERPOD_PASSWORD_` prefix. ## Run mode Config files by mode: `config/development.yaml`, `config/staging.yaml`, `config/production.yaml`, `config/test.yaml`. Set via `--mode` when starting server or `SERVERPOD_RUN_MODE` (default: `development`). ## API server (minimum) ```yaml apiServer: port: 8080 publicHost: localhost publicPort: 8080 publicScheme: http ``` `port` is the port the listener binds. `publicHost`/`publicPort`/`publicScheme` are used for URLs returned to clients; a `publicPort` of 0 follows the bound port. In development the Serverpod runner keeps the configured ports unless another runner on the machine holds them, in which case it binds ephemeral ports (through `SERVERPOD_API_SERVER_PORT`, its siblings and `SERVERPOD_DATABASE_PORT`; the `_PUBLIC_PORT` variables of the api, insights and web listeners carry the same value, so URLs returned to clients use the bound port) and publishes the real addresses in `serverpod runner status`. See [Several servers at once](../serverpod-overview/SKILL.md#several-servers-at-once) in the overview skill. ## Database It is possible to use either PostgreSQL or SQLite as the database. ### PostgreSQL ```yaml database: host: localhost port: 8090 name: my_project user: postgres dataPath: .serverpod/development/pgdata # embedded database, see below ``` Password in `passwords.yaml` under run mode or `SERVERPOD_PASSWORD_database`. Optional: `searchPaths`, `maxConnectionCount`, `requireSsl`, `isUnixSocket`. **Embedded PostgreSQL:** with `dataPath` set, Serverpod launches and manages a PostgreSQL instance in that directory, so nothing has to be installed or run separately. New projects use it for development and testing. It listens on its Unix socket, plus loopback TCP on `port` when the run mode has a database password. In development the runner moves that port aside with the server ports when another Serverpod runner holds it, so several checkouts can run their own at once. `serverpod database start [--mode <mode>] [--port <port>]` boots the same database on its own, without the server, or joins the one the server already runs. Without `dataPath` the database is external, and the runner (`serverpod start`) starts Docker Compose services when the project has a compose file and PostgreSQL is on localhost (`--docker` / `--no-docker` override this). ### SQLite ```yaml database: filePath: my_project.sqlite ``` No password is needed for SQLite. ## Redis `redis.enabled`, `redis.host`, `redis.port`; password via `SERVERPOD_PASSWORD_redis`. ## Secrets (passwords.yaml) Structure: `shared:` (all modes) + per-mode (`development:`, `production:`, etc.). Built-in keys: `database`, `redis`, `serviceSecret`. Custom keys available via `session.passwords['key']` or `pod.getPassword('key')`. The built-in passwords also have dedicated environment variables: `SERVERPOD_DATABASE_PASSWORD`, `SERVERPOD_REDIS_PASSWORD` and `SERVERPOD_SERVICE_SECRET`. Any password, built-in or custom, can also be set with the `SERVERPOD_PASSWORD_` prefix. ```bash export SERVERPOD_PASSWORD_stripeApiKey=sk_live_... # → session.passwords['stripeApiKey'] ``` Never commit real secrets; use env vars in production. ## generator.yaml In `config/generator.yaml`: - `type`: `server` (default), `module`, or `internal` - `client_package_path`: path to client package - `modules`: map of module names + optional `nickname` - `server_test_tools_path`: test tools output path (remove to disable) - `extraClasses`: custom serializable class URIs - `features`: e.g. `database: true/false` ## Dart config override Pass `config: ServerpodConfig(...)` to `Serverpod(...)` to skip file/env loading and use a Dart config object, with CLI flags still merged in. For tests, it is possible to use `configOverride: (config) => config.copyWith(...)` to adjust the loaded config after YAML/env/CLI processing. ## TLS/SSL Pass `SecurityContextConfig` to `Serverpod(...)` with a `SecurityContext` that loads cert chain and private key. Set on `apiServer`, `webServer`, and/or `insightsServer`. Client: pass `SecurityContext` with trusted certificates to `Client(...)`. ## Reference files - [`references/environment-variables.md`](references/environment-variables.md) — the full `SERVERPOD_*` environment variable table. - [`references/flutter-apps.md`](references/flutter-apps.md) — declaring the Flutter apps that `serverpod start` can launch.