# Serverpod Configuration

> Serverpod Configuration is an Agent Skill for devops & security published in the serverpod/serverpod repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Configure Serverpod — YAML config, environment variables, passwords, run modes, generator.yaml, TLS. Use when setting up environments, API/database/Redis settings, managing secrets or overriding configurations for tests.

- Skill name: `serverpod-configuration`
- Category: [DevOps & Security](https://www.openparable.com/skill/devops-security/1)
- Source: https://github.com/serverpod/serverpod/blob/HEAD/packages/serverpod/skills/serverpod-configuration/SKILL.md
- Repository: serverpod/serverpod (3,224 GitHub stars when collected)

## SKILL.md

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

`publicHost`/`publicPort`/`publicScheme` are used for URLs returned to clients.

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

Password in `passwords.yaml` under run mode or `SERVERPOD_PASSWORD_database`. Optional: `searchPaths`, `maxConnectionCount`, `requireSsl`, `isUnixSocket`.

### 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`.

## Environment variables reference

| Category | Env var | YAML / default |
| -------- | ------- | -------------- |
| Server | `SERVERPOD_RUN_MODE` | `--mode` / development |
| | `SERVERPOD_SERVER_ID` | serverId |
| | `SERVERPOD_SERVER_ROLE` | role (monolith\|serverless\|maintenance) |
| | `SERVERPOD_LOGGING_MODE` | logging (normal\|verbose) |
| | `SERVERPOD_APPLY_MIGRATIONS` | applyMigrations |
| | `SERVERPOD_APPLY_REPAIR_MIGRATION` | applyRepairMigration |
| API server | `SERVERPOD_API_SERVER_PORT` | apiServer.port / 8080 |
| | `SERVERPOD_API_SERVER_PUBLIC_HOST` | apiServer.publicHost |
| | `SERVERPOD_API_SERVER_PUBLIC_PORT` | apiServer.publicPort |
| | `SERVERPOD_API_SERVER_PUBLIC_SCHEME` | apiServer.publicScheme |
| Insights | `SERVERPOD_INSIGHTS_SERVER_PORT` | insightsServer.port |
| Web | `SERVERPOD_WEB_SERVER_PORT` | webServer.port |
| Database | `SERVERPOD_DATABASE_HOST` | database.host |
| | `SERVERPOD_DATABASE_PORT` | database.port |
| | `SERVERPOD_DATABASE_NAME` | database.name |
| | `SERVERPOD_DATABASE_USER` | database.user |
| | `SERVERPOD_DATABASE_REQUIRE_SSL` | database.requireSsl |
| | `SERVERPOD_DATABASE_IS_UNIX_SOCKET` | database.isUnixSocket |
| | `SERVERPOD_DATABASE_SEARCH_PATHS` | database.searchPaths |
| | `SERVERPOD_DATABASE_MAX_CONNECTION_COUNT` | database.maxConnectionCount / 10 |
| | `SERVERPOD_DATABASE_FILE_PATH` | database.filePath |
| Redis | `SERVERPOD_REDIS_HOST`, `_PORT`, `_USER`, `_ENABLED`, `_REQUIRE_SSL` | redis.* |
| Other | `SERVERPOD_MAX_REQUEST_SIZE` | maxRequestSize / 524288 |
| | `SERVERPOD_WEBSOCKET_PING_INTERVAL` | websocketPingInterval / 30s |
| | `SERVERPOD_FUTURE_CALL_EXECUTION_ENABLED` | futureCallExecutionEnabled |
| | `SERVERPOD_FUTURE_CALL_CONCURRENCY_LIMIT` | futureCall.concurrencyLimit |
| | `SERVERPOD_FUTURE_CALL_SCAN_INTERVAL` | futureCall.scanInterval (ms) |
| Session logs | `SERVERPOD_SESSION_PERSISTENT_LOG_ENABLED` | sessionLogs.persistentEnabled |
| | `SERVERPOD_SESSION_CONSOLE_LOG_ENABLED` | sessionLogs.consoleEnabled |
| | `SERVERPOD_SESSION_CONSOLE_LOG_FORMAT` | sessionLogs.consoleLogFormat (text\|json) |
| | `SERVERPOD_SESSION_LOG_CLEANUP_INTERVAL` | sessionLogs.cleanupInterval |
| | `SERVERPOD_SESSION_LOG_RETENTION_PERIOD` | sessionLogs.retentionPeriod |
| | `SERVERPOD_SESSION_LOG_RETENTION_COUNT` | sessionLogs.retentionCount |

## 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')`.

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

## Flutter apps (pubspec.yaml)

Companion Flutter apps that `serverpod start` can launch (Ctrl+R) are declared
in the server `pubspec.yaml` under `serverpod: flutter_apps:`, a map of display
alias to properties (alongside `serverpod: scripts:`):

- `path`: path to the Flutter package, relative to the server package.
- `displayName`: optional human-readable label for TUI tab names. When omitted,
  the app id is used.
- `auto_launch`: launch this app automatically on `serverpod start`. Apps
  without it are launched on demand with `Ctrl+R`.
- `device`: the `flutter run -d` target. Defaults to the web server (opening a
  browser when ready) when omitted.

**Any other property** is forwarded to `flutter run`: `target: lib/main.dart`
becomes `--target=lib/main.dart`, `release: true` becomes `--release`,
`release: false` becomes `--no-release`, and a list value repeats the flag
(`dart-define: [A=1, B=2]` becomes `--dart-define=A=1 --dart-define=B=2`).

When the key is absent, the sibling `../<project>_flutter` package is used
automatically (and auto-launched) if present.

```yaml
serverpod:
  flutter_apps:
    Admin:
      path: ../apps/admin
      displayName: "Admin app"
      auto_launch: true
      device: chrome
      target: lib/main.dart
    Portal:
      path: ../apps/portal
```

## 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(...)`.

---

Source: https://www.openparable.com/skill/devops-security/serverpod-configuration (OpenParable). Cite the canonical URL above.