# Configuration reference https://docs.serverpod.dev/concepts/lookups/configuration-reference Every configuration option Serverpod's core library reads. Options come from three sources: the `config/.yaml` files, environment variables, and the `ServerpodConfig` Dart object. Environment variables override the YAML files. If you pass a `ServerpodConfig` to the `Serverpod` constructor, the server ignores the YAML files and environment variables. Command-line options such as `--mode` still override the values in your `ServerpodConfig`. For how to choose between them, see [Configuration](https://docs.serverpod.dev/concepts/server-fundamentals/configuration.md). ## Run options Set the run mode, server role, and boot behavior. Declare each per run mode in the matching `config/.yaml`, or as an environment variable. | Environment variable | Command line option | Config file option | Default | Description | | ----------------------------------- | -------------------------- | -------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- | | SERVERPOD\_RUN\_MODE | `--mode` | N/A | development | Configures the mode of the server instance. Valid options are `development`, `staging`, `production` and `test`. | | SERVERPOD\_SERVER\_ID | `--server-id` | serverId | default | Configures the id of the server instance. | | SERVERPOD\_SERVER\_ROLE | `--role` | role | monolith | Configures the role of the server instance. Valid options are `monolith`, `serverless` and `maintenance`. | | SERVERPOD\_LOGGING\_MODE | `--logging` | logging | normal | Configures the logging level. Valid options are `normal`, and `verbose`. | | SERVERPOD\_APPLY\_MIGRATIONS | `--apply-migrations` | applyMigrations | false | Configures if migrations should be applied when the server starts. | | SERVERPOD\_APPLY\_REPAIR\_MIGRATION | `--apply-repair-migration` | applyRepairMigration | false | Configures if repair migrations should be applied when the server starts. | ## Server and services Ports, hosts, and connection settings for the API, Insights, and web servers, the database, Redis, session logs, and future calls, plus a few options that exist only on the Dart config object or as environment variables. | Environment variable | Config file | Default | Description | | ----------------------------------------------------- | ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | SERVERPOD\_API\_SERVER\_PORT | apiServer.port | 8080 | The port number for the API server | | SERVERPOD\_API\_SERVER\_PUBLIC\_HOST | apiServer.publicHost | localhost | The public host address of the API server | | SERVERPOD\_API\_SERVER\_PUBLIC\_PORT | apiServer.publicPort | 8080 | The public port number for the API server | | SERVERPOD\_API\_SERVER\_PUBLIC\_SCHEME | apiServer.publicScheme | http | The public scheme (http/https) for the API server | | SERVERPOD\_INSIGHTS\_SERVER\_PORT | insightsServer.port | - | The port number for the Insights server | | SERVERPOD\_INSIGHTS\_SERVER\_PUBLIC\_HOST | insightsServer.publicHost | - | The public host address of the Insights server | | SERVERPOD\_INSIGHTS\_SERVER\_PUBLIC\_PORT | insightsServer.publicPort | - | The public port number for the Insights server | | SERVERPOD\_INSIGHTS\_SERVER\_PUBLIC\_SCHEME | insightsServer.publicScheme | - | The public scheme (http/https) for the Insights server | | SERVERPOD\_INSIGHTS\_SERVER\_ENABLE\_DATABASE\_ACCESS | insightsServer.enableDatabaseAccess | false | Whether the Insights server serves the direct database access endpoints (used by custom service client tooling, not the Insights app) | | SERVERPOD\_WEB\_SERVER\_PORT | webServer.port | - | The port number for the Web server | | SERVERPOD\_WEB\_SERVER\_PUBLIC\_HOST | webServer.publicHost | - | The public host address of the Web server | | SERVERPOD\_WEB\_SERVER\_PUBLIC\_PORT | webServer.publicPort | - | The public port number for the Web server | | SERVERPOD\_WEB\_SERVER\_PUBLIC\_SCHEME | webServer.publicScheme | - | The public scheme (http/https) for the Web server | | SERVERPOD\_WEB\_SERVER\_STATIC\_CACHE\_CONTROL | N/A | - | The `Cache-Control` header for `StaticRoute` responses without a `cacheControlFactory`. See [Static files](https://docs.serverpod.dev/concepts/web-server/static-files.md#cache-control). | | SERVERPOD\_WEB\_SERVER\_SPA\_CACHE\_CONTROL | N/A | - | The `Cache-Control` header for `SpaRoute` responses without a `cacheControlFactory`. Never applies to the fallback file. See [Single-page apps](https://docs.serverpod.dev/concepts/web-server/single-page-apps.md#cache-control). | | SERVERPOD\_WEB\_SERVER\_FLUTTER\_CACHE\_CONTROL | N/A | - | The `Cache-Control` header for `FlutterRoute` responses without a `cacheControlFactory`. See [Flutter web](https://docs.serverpod.dev/concepts/web-server/flutter-web.md#cache-control). | | SERVERPOD\_DATABASE\_HOST | database.host | - | The host address of the database | | SERVERPOD\_DATABASE\_PORT | database.port | - | The port number for the database connection | | SERVERPOD\_DATABASE\_NAME | database.name | - | The name of the database | | SERVERPOD\_DATABASE\_USER | database.user | - | The user name for database authentication | | SERVERPOD\_DATABASE\_SEARCH\_PATHS | database.searchPaths | - | The search paths used for all database connections | | SERVERPOD\_DATABASE\_REQUIRE\_SSL | database.requireSsl | false | Indicates if SSL is required for the database | | SERVERPOD\_DATABASE\_IS\_UNIX\_SOCKET | database.isUnixSocket | false | Specifies if the database connection is a Unix socket | | SERVERPOD\_DATABASE\_MAX\_CONNECTION\_COUNT | database.maxConnectionCount | 10 | The maximum number of connections in the database pool. Set to 0 or a negative value for unlimited connections. | | N/A | database.filePath | - | The SQLite database file path. Set this instead of host/port/name/user when using SQLite. Config file only. | | N/A | database.dialect | Inferred | The database dialect. Valid options are `postgres` and `sqlite`. When unset, a `filePath` selects SQLite, and host/port/name/user select PostgreSQL. Config file only. | | SERVERPOD\_DATABASE\_DATA\_PATH | database.dataPath | - | Directory for the embedded PostgreSQL cluster, relative to the server package unless absolute. When set, Serverpod starts or attaches to the cluster before connecting. PostgreSQL only; ignored for SQLite. | | SERVERPOD\_REDIS\_HOST | redis.host | - | The host address of the Redis server | | SERVERPOD\_REDIS\_PORT | redis.port | - | The port number for the Redis server | | SERVERPOD\_REDIS\_USER | redis.user | - | The user name for Redis authentication | | SERVERPOD\_REDIS\_ENABLED | redis.enabled | true | Indicates if Redis is enabled. Defaults to `true` when a `redis` section is present; Redis is off when the section is absent or `enabled` is `false`. | | SERVERPOD\_REDIS\_REQUIRE\_SSL | redis.requireSsl | false | Indicates if SSL is required for the Redis connection | | SERVERPOD\_MAX\_REQUEST\_SIZE | maxRequestSize | 524288 | The maximum size of API requests in bytes. Also caps file uploads that post to the API server. | | SERVERPOD\_VALIDATE\_HEADERS | validateHeaders | true | Validate HTTP headers using the typed API. Set to `false` to accept headers without the required formatting, for example an unwrapped token in the Authorization header. | | SERVERPOD\_ALLOWED\_ORIGINS | allowedOrigins | - | Browser origins allowed to make credentialed cross-origin calls, as `scheme://host[:port]`. A YAML list, or comma-separated in the environment variable. Required when `authCookie` is set. When set, browser WebSocket connections for [streaming](https://docs.serverpod.dev/concepts/endpoints-and-apis/streaming.md) from other origins are also rejected, with or without `authCookie`. See [Web authentication](https://docs.serverpod.dev/concepts/authentication/web-authentication.md). | | SERVERPOD\_AUTH\_COOKIE\_NAME | authCookie.name | - | Name of the auth cookie. Defaults to `serverpod_auth`. Setting any `authCookie` field enables cookie auth for web clients; an empty `authCookie` section is read as unset. | | SERVERPOD\_AUTH\_COOKIE\_REFRESH\_NAME | authCookie.refreshName | - | Name of the JWT refresh cookie. Defaults to `_refresh`. | | SERVERPOD\_AUTH\_COOKIE\_DOMAIN | authCookie.domain | - | Cookie `Domain` attribute. Defaults to host-only; set to share the cookie across subdomains. | | SERVERPOD\_AUTH\_COOKIE\_PATH | authCookie.path | / | Cookie `Path` attribute. | | SERVERPOD\_AUTH\_COOKIE\_SECURE | authCookie.secure | true | Whether the cookie is only sent over https. Set to `false` only for `http://localhost` development. | | SERVERPOD\_AUTH\_COOKIE\_SAME\_SITE | authCookie.sameSite | lax | Cookie `SameSite` attribute. Valid options are `lax`, `strict`, and `none` (`none` requires `secure`). | | SERVERPOD\_SESSION\_PERSISTENT\_LOG\_ENABLED | sessionLogs.persistentEnabled | - | Enables or disables logging session data to the database. Defaults to `true` if a database is configured, otherwise `false`. | | SERVERPOD\_SESSION\_LOG\_CLEANUP\_INTERVAL | sessionLogs.cleanupInterval | - | How often to run the log cleanup job. Duration string, for example `24h` or `2d`. Set to null to disable automated purging. Defaults to `24h` only when `sessionLogs` is not configured at all. See [Purge old records](https://docs.serverpod.dev/concepts/operations/logging.md#purge-old-records). | | SERVERPOD\_SESSION\_LOG\_RETENTION\_PERIOD | sessionLogs.retentionPeriod | - | How long to keep session log entries. Duration string, for example `30d` or `60d`. Set to null to disable time-based cleanup. Defaults to `90d` only when `sessionLogs` is not configured at all. See [Purge old records](https://docs.serverpod.dev/concepts/operations/logging.md#purge-old-records). | | SERVERPOD\_SESSION\_LOG\_RETENTION\_COUNT | sessionLogs.retentionCount | - | Maximum number of session log entries to keep. Set to null to disable count-based cleanup. Defaults to `100000` only when `sessionLogs` is not configured at all. See [Purge old records](https://docs.serverpod.dev/concepts/operations/logging.md#purge-old-records). | | SERVERPOD\_SESSION\_CONSOLE\_LOG\_ENABLED | sessionLogs.consoleEnabled | - | Enables or disables logging session data to the console. Defaults to `true` if no database is configured or the run mode is `development`, otherwise `false`. | | SERVERPOD\_SESSION\_CONSOLE\_LOG\_FORMAT | sessionLogs.consoleLogFormat | - | The format for console logging of session data. Valid options are `text` and `json`. Defaults to `text` for run mode `development`, otherwise `json`. | | SERVERPOD\_FUTURE\_CALL\_EXECUTION\_ENABLED | futureCallExecutionEnabled | true | Enables or disables the execution of future calls. | | SERVERPOD\_FUTURE\_CALL\_CONCURRENCY\_LIMIT | futureCall.concurrencyLimit | 1 | The maximum number of concurrent future calls allowed. If the value is negative or null, no limit is applied. | | SERVERPOD\_FUTURE\_CALL\_SCAN\_INTERVAL | futureCall.scanInterval | 5000 | The interval in milliseconds for scanning future calls | | SERVERPOD\_FUTURE\_CALL\_CHECK\_BROKEN\_CALLS | futureCall.checkBrokenCalls | - | Enables or disables the automatic check for broken future calls on startup. By default, the server performs an automatic check if there are less than 1000 calls in the database. | | SERVERPOD\_FUTURE\_CALL\_DELETE\_BROKEN\_CALLS | futureCall.deleteBrokenCalls | false | Enables or disables the deletion of broken future calls when running the check on startup. | | SERVERPOD\_WEBSOCKET\_PING\_INTERVAL | websocketPingInterval | 30 | The interval in seconds between WebSocket ping messages sent to keep streaming connections alive. Must be a positive integer. | ### Dart-only options These options have no environment variable or config-file key. Set them on the `ServerpodConfig` Dart object passed to the `Serverpod` constructor. | ServerpodConfig field | Default | Description | | ------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------- | | healthCheckInterval | 1m | How often the server collects health metrics. Set to zero to disable health checks. | | experimentalDiagnosticHandlerTimeout | 30s | The timeout for [diagnostic event handlers](https://docs.serverpod.dev/concepts/operations/exception-monitoring.md). | ### Password environment variables Secrets are read from `config/passwords.yaml` and can be overridden per secret through environment variables; see [Manage secrets](https://docs.serverpod.dev/concepts/server-fundamentals/configuration.md#manage-secrets). Two forms exist, and when both are set for the same secret, the `SERVERPOD_PASSWORD_*` form wins: | Environment variable | Overrides passwords-file key | | ----------------------------- | -------------------------------------------------------------------------------- | | `SERVERPOD_PASSWORD_` | Any secret; the prefix is stripped (`SERVERPOD_PASSWORD_database` → `database`). | | SERVERPOD\_DATABASE\_PASSWORD | database | | SERVERPOD\_SERVICE\_SECRET | serviceSecret | | SERVERPOD\_REDIS\_PASSWORD | redis | ## Code generation Options for `config/generator.yaml`, which configures `serverpod generate`. | Option | Type | Default | Description | | --------------------------------- | ------ | ---------------------------- | ------------------------------------------------------------------------------------------- | | type | string | server | The package type. Valid options are `server`, `module`, or `internal`. | | nickname | string | - | For modules only. Defines how the module is referenced in code. | | client\_package\_path | string | ../\[name]\_client | Path to the client package relative to the server. | | server\_test\_tools\_path | string | test/integration/test\_tools | Path where test tools are generated. Remove this to disable test tools generation. | | shared\_packages | list | - | Paths to shared packages containing models usable by both server and client. | | modules | map | - | Module dependencies with optional nicknames. | | extraClasses | list | - | List of custom serializable classes to include in code generation. | | serialize\_as\_jsonb\_by\_default | bool | false | When true, all serializable fields default to `jsonb` storage instead of `json`. | | features | map | {database: true} | Feature flags. Currently only `database` is supported. | | experimental\_features | map | - | Experimental features. Available keys: `databaseSync` (enables `database: sync`) and `all`. | ## Related - [Configuration](https://docs.serverpod.dev/concepts/server-fundamentals/configuration.md): how the three configuration sources work, run modes, secrets, and package types. - [Redis](https://docs.serverpod.dev/concepts/operations/redis.md): enabling Redis, the password, and connecting a GUI. - [Running your server](https://docs.serverpod.dev/concepts/server-fundamentals/running-your-server.md): the run mode and files the server loads on start.