# Configurations
https://docs.serverpod.dev/2.9.0/concepts/configuration
Serverpod can be configured in a few different ways. The minimum required settings to provide is the configuration for the API server. If no settings are provided at all, the default settings for the API server are used.
## Configuration options
There are three different ways to configure Serverpod: with environment variables, via yaml config files, or by supplying the dart configuration object to the Serverpod constructor. The environment variables take precedence over the yaml configurations but both can be used simultaneously. The dart configuration object will override any environment variable or config file. The tables show all available configuration options provided in the Serverpod core library.
```mermaid
flowchart TB
%% ── widest box first so YAML feels like the default bedrock
A["YAML config files
(default)"]:::yaml
B["Environment variables
(overrides YAML)"]:::env
C["Dart configuration object
(overrides YAML and ENV)"]:::dart
A --> B
B --> C
%% Styles (optional – tweak to your theme)
class A yaml
class B env
class C dart
```
### Configuration options for the server
| 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. |
These can be separately declared for each run mode in the corresponding yaml file (`development.yaml`,`staging.yaml`, `production.yaml` and `testing.yaml`) 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\_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\_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\_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 | false | Indicates if Redis is enabled |
| 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 requests allowed in bytes |
| 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\_CONSOLE\_LOG\_ENABLED | sessionLogs.consoleEnabled | - | Enables or disables logging session data to the console. Defaults to `true` if no database is configured, otherwise `false`. |
| SERVERPOD\_SESSION\_CONSOLE\_LOG\_FORMAT | sessionLogs.consoleLogFormat | json | 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 |
### Secrets
Secrets are declared in the `passwords.yaml` file. The password file is structured with a common `shared` section, any secret put here will be used in all run modes. The other sections are the names of the run modes followed by respective key/value pairs. You can also define custom secrets using [environment variables](#2-via-environment-variables).
#### Built-in Secrets
The following table shows the built-in secrets that Serverpod uses for its core functionality. These can be configured either through environment variables or by adding the corresponding key in a respective run mode or shared section in the passwords file. These are separate from any custom passwords you might define.
| Environment variable | Passwords file | Default | Description |
| ---------------------------------- | -------------- | ------- | ----------------------------------------------------------------- |
| SERVERPOD\_PASSWORD\_database | database | - | The password for the database |
| SERVERPOD\_PASSWORD\_serviceSecret | serviceSecret | - | The token used to connect with insights must be at least 20 chars |
| SERVERPOD\_PASSWORD\_redis | redis | - | The password for the Redis server |
#### Secrets for First Party Packages
The following secrets are used by official Serverpod packages:
- [serverpod\_cloud\_storage\_gcp](https://pub.dev/packages/serverpod_cloud_storage_gcp): Google Cloud Storage
- [serverpod\_cloud\_storage\_s3](https://pub.dev/packages/serverpod_cloud_storage_s3): Amazon S3
- [serverpod\_auth\_server](https://pub.dev/packages/serverpod_auth_server): Serverpod Auth Server
| Environment variable | Passwords file | Default | Description |
| --------------------------------------------------------------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------- |
| SERVERPOD\_PASSWORD\_HMACAccessKeyId | HMACAccessKeyId | - | The access key ID for HMAC authentication for serverpod\_cloud\_storage\_gcp |
| SERVERPOD\_PASSWORD\_HMACSecretKey | HMACSecretKey | - | The secret key for HMAC authentication for serverpod\_cloud\_storage\_gcp |
| SERVERPOD\_PASSWORD\_AWSAccessKeyId | AWSAccessKeyId | - | The access key ID for AWS authentication for serverpod\_cloud\_storage\_s3 |
| SERVERPOD\_PASSWORD\_AWSSecretKey | AWSSecretKey | - | The secret key for AWS authentication for serverpod\_cloud\_storage\_s3 |
| SERVERPOD\_PASSWORD\_serverpod\_auth\_googleClientSecret | serverpod\_auth\_googleClientSecret | - | The client secret for Google authentication for serverpod\_auth\_server |
| SERVERPOD\_PASSWORD\_serverpod\_auth\_firebaseServiceAccountKey | serverpod\_auth\_firebaseServiceAccountKey | - | The service account key for Firebase authentication for serverpod\_auth\_server |
#### Custom Secrets
You can define your own custom secrets in two ways.
##### 1. Via Passwords File
Add your custom secrets directly to the passwords file under the `shared` section (available in all run modes) or under specific run mode sections.
```yaml
shared:
myCustomSharedSecret: 'secret_key'
stripeApiKey: 'sk_test_123...'
development:
database: 'development_password'
redis: 'development_password'
serviceSecret: 'development_service_secret'
twilioApiKey: 'dev_twilio_key'
production:
database: 'production_password'
redis: 'production_password'
serviceSecret: 'production_service_secret'
twilioApiKey: 'prod_twilio_key'
```
##### 2. Via Environment Variables
You can also define custom passwords using environment variables with the `SERVERPOD_PASSWORD_` prefix. For example, `SERVERPOD_PASSWORD_myApiKey` will be available as `myApiKey` (the prefix is stripped). These environment variables will override any passwords defined in the passwords file if the name (after stripping the prefix) matches. Like the `shared` section in the passwords file, these environment variables are available in all run modes.
| Environment variable format | Description |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| SERVERPOD\_PASSWORD\_\* | Custom password that will be available in the Session.passwords map. The prefix `SERVERPOD_PASSWORD_` will be stripped from the key name. |
**Example:**
To define a custom password through an environment variable:
```bash
export SERVERPOD_PASSWORD_stripeApiKey=sk_test_123...
```
**Accessing Custom Passwords:**
You can then access any custom password (whether defined in the passwords file or via environment variables) in your endpoint code through the `Session.passwords` map:
```dart
Future processPayment(Session session, PaymentData data) async {
final stripeApiKey = session.passwords['stripeApiKey'];
// Use the API key to make requests to Stripe
...
}
```
### Config file example
The config file should be named after the run mode you start the server in and it needs to be placed inside the `config` directory in the root of the server project. As an example, you have the `config/development.yaml` that will be used when running in the `development` run mode.
```yaml
apiServer:
port: 8080
publicHost: localhost
publicPort: 8080
publicScheme: http
insightsServer:
port: 8081
publicHost: localhost
publicPort: 8081
publicScheme: http
webServer:
port: 8082
publicHost: localhost
publicPort: 8082
publicScheme: http
database:
host: localhost
port: 8090
name: database_name
user: postgres
redis:
enabled: false
host: localhost
port: 8091
maxRequestSize: 524288
sessionLogs:
persistentEnabled: true
consoleEnabled: true
consoleLogFormat: json
futureCallExecutionEnabled: true
futureCall:
concurrencyLimit: 5
scanInterval: 2000
```
### Passwords file example
The password file contains the secrets used by the server to connect to different services but you can also supply your secrets if you want. This file is structured with a common `shared` section, any secret put here will be used in all run modes. The other sections are the names of the run modes followed by respective key/value pairs.
```yaml
shared:
myCustomSharedSecret: 'secret_key'
development:
database: 'development_password'
redis: 'development_password'
serviceSecret: 'development_service_secret'
twilioApiKey: 'dev_twilio_key'
production:
database: 'production_password'
redis: 'production_password'
serviceSecret: 'production_service_secret'
twilioApiKey: 'prod_twilio_key'
```
### Dart config object example
To configure Serverpod in Dart you simply pass an instance of the `ServerpodConfig` class to the `Serverpod` constructor. This config will override any environment variables or config files present. The `Serverpod` constructor is normally used inside the `run` function in your `server.dart` file. At a minimum, the `apiServer` has to be provided.
```dart
Serverpod(
args,
Protocol(),
Endpoints(),
config: ServerpodConfig(
apiServer: ServerConfig(
port: 8080,
publicHost: 'localhost',
publicPort: 8080,
publicScheme: 'http',
),
insightsServer: ServerConfig(
port: 8081,
publicHost: 'localhost',
publicPort: 8081,
publicScheme: 'http',
),
webServer: ServerConfig(
port: 8082,
publicHost: 'localhost',
publicPort: 8082,
publicScheme: 'http',
),
),
);
```
### Default
If no yaml config files exist, no environment variables are configured and no dart config file is supplied this default configuration will be used.
```dart
ServerpodConfig(
apiServer: ServerConfig(
port: 8080,
publicHost: 'localhost',
publicPort: 8080,
publicScheme: 'http',
),
);
```
## Code generation configuration
While the above configurations control how your server runs, Serverpod also uses a `generator.yaml` file to configure code generation. This file should be placed in the `config` directory of your server project.
### Generator configuration options
| 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. |
| modules | map | - | Module dependencies with optional nicknames. |
| extraClasses | list | - | List of custom serializable classes to include in code generation. |
| features | map | {database: true} | Feature flags. Currently only `database` is supported. |
| experimental\_features | map | - | Experimental features. Available keys: `all`, `inheritance`. |
### Package types
The `type` field determines how Serverpod treats your package:
- **server**: A standard Serverpod application (default)
- **module**: A reusable module that can be imported by other Serverpod projects
- **internal**: Internal Serverpod framework packages
For modules, you can also specify a `nickname`:
```yaml
type: module
nickname: auth
```
### Client package path
By default, Serverpod expects the client package to be located at `../[project_name]_client`. You can customize this:
```yaml
client_package_path: ../my_custom_client
```
### Test tools generation
Test tools for integration testing are generated by default at `test/integration/test_tools`. To disable test tools generation, remove the `server_test_tools_path` from your configuration:
```yaml
# Remove or comment out this line to disable test tools
# server_test_tools_path: test/integration/test_tools
```
See the [testing documentation](https://docs.serverpod.dev/2.9.0/concepts/testing/get-started.md) for more details.
### Module dependencies
Declare module dependencies and optionally assign nicknames for easier reference:
```yaml
modules:
serverpod_auth:
nickname: auth
my_custom_module:
nickname: custom
```
This allows you to reference module classes as `module:auth:UserInfo` in your model files. See the [modules documentation](https://docs.serverpod.dev/2.9.0/concepts/modules.md) for more information.
### Custom serializable classes
Register custom classes for use in your models:
```yaml
extraClasses:
- package:my_shared_package/my_shared_package.dart:CustomClass
- package:my_shared_package/my_shared_package.dart:AnotherCustomClass
```
See the [serialization documentation](https://docs.serverpod.dev/2.9.0/concepts/serialization.md) for implementing custom serializable classes.
### Features
Control which Serverpod features are enabled:
```yaml
features:
database: false # Disables database features
```
### Experimental features
Enable experimental features that are still in development:
```yaml
experimental_features:
inheritance: true # Enables class inheritance in model files
# or
all: true # Enables all experimental features
```
Available experimental features:
- `inheritance`: Enables the `extends` keyword in model files for class inheritance
- `all`: Enables all available experimental features
See the [experimental features documentation](https://docs.serverpod.dev/2.9.0/concepts/experimental.md) for detailed information about each feature.
:::warning
Experimental features may change or be removed in future versions.
:::