diff --git a/docs/04-get-started/03-how-it-works.md b/docs/04-get-started/03-how-it-works.md index a9d060b4..39b74986 100644 --- a/docs/04-get-started/03-how-it-works.md +++ b/docs/04-get-started/03-how-it-works.md @@ -30,7 +30,7 @@ my_project/ └── my_project_flutter/ # Your Flutter app. ``` -In the `_server` package you add your endpoints and data models. Serverpod's code generator generates code on the server and in the client package. You get a type-safe Dart API for your app, along with the serialization and database code on the server. You never write serialization, HTTP calls, or API contracts. +In the `_server` package you add your endpoints and data models. Serverpod's code generator generates code on the server and in the client package. You get a type-safe Dart API for your app, along with the serialization and database code on the server. You never write serialization, HTTP calls, or API contracts. For what each package holds in detail, see [Your Serverpod project](./concepts/server-fundamentals/your-serverpod-project). ## Run your project diff --git a/docs/06-concepts/01-server-fundamentals/01-running-your-server.md b/docs/06-concepts/01-server-fundamentals/01-running-your-server.md deleted file mode 100644 index d61fc513..00000000 --- a/docs/06-concepts/01-server-fundamentals/01-running-your-server.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -description: The serverpod start command runs your project in development, with code generation, hot reload, database migrations, and the Flutter app in one terminal. ---- - -# Running your server - -As you build, one command keeps your server, generated code, and app in sync, so a change shows up the moment you save. The `serverpod start` command does exactly that: it generates the latest code, runs your server with hot reload, and launches your companion Flutter apps, all inside a single interactive terminal. - -Run it from anywhere inside your project folder: - -```bash -serverpod start -``` - -Use `serverpod start` for local development only. To run your server in production, deploy it instead. See [Deploy to Serverpod Cloud](../../deployments/deploy-to-serverpod-cloud) or [Custom hosting](../../deployments/custom-hosting/choosing-a-strategy). - -## Save a file to hot-reload - -While `serverpod start` is watching, which is the default, saving a file recompiles and hot-reloads the affected code without a restart. This covers your endpoints, models, and generated client, so the running server and the generated code stay in step as you work. When a change cannot be hot-reloaded, press **R** in the terminal to hot restart. - -To start without watching, pass `--no-watch`. The server then runs through `dart run` with no incremental compilation. - -## Manage migrations from the terminal - -On boot, `serverpod start` applies any pending migrations. While it runs, you handle further schema changes from the interactive terminal without leaving the session. The terminal lists these shortcuts along the bottom: - -- **M** creates a migration from your current model changes. -- **A** applies pending migrations to the database. -- **P** creates a repair migration to reconcile a database that has drifted from your migrations. - -For how migrations work, see [Migrations](../data-and-the-database/database/migrations). - -## Choose a run mode - -By default, `serverpod start` runs in the `development` run mode. To start in another mode, forward a `--mode` argument to the server after `--`: - -```bash -serverpod start -- --mode staging -``` - -The run mode selects which configuration and passwords the server loads. See [Configuration](configuration) for what each mode reads. - -## Run the server on its own - -By default, `serverpod start` also launches the companion Flutter apps marked `auto_launch: true` in the server's `pubspec.yaml`. To start only the server, disable that: - -```bash -serverpod start --no-flutter -``` - -You can still launch an app on demand from the terminal afterwards. To run without the interactive terminal at all, for a script or CI, pass `--no-tui`. - -## Related - -- [`serverpod start` reference](../cli/commands/start): every command-line option. -- [Configuration](configuration): the run modes and files the server loads on start. -- [Deploy to Serverpod Cloud](../../deployments/deploy-to-serverpod-cloud): run your server in production instead of locally. diff --git a/docs/06-concepts/01-server-fundamentals/01-your-serverpod-project.md b/docs/06-concepts/01-server-fundamentals/01-your-serverpod-project.md new file mode 100644 index 00000000..0d7b0d80 --- /dev/null +++ b/docs/06-concepts/01-server-fundamentals/01-your-serverpod-project.md @@ -0,0 +1,127 @@ +--- +description: A Serverpod project is one Dart workspace with three packages, the server, the generated client, and your Flutter app, plus its config and migrations. +--- + +# Your Serverpod project + +A Serverpod project is one workspace holding three Dart packages: your server, a generated client, and your Flutter app. You write data models and endpoints on the server; Serverpod generates everything between them, so your app calls the server through typed Dart methods instead of hand-written networking code. Knowing what lives where makes every other page in this section easier to follow. + +Running `serverpod create myproject` generates one workspace with three packages: + +```text +myproject/ +├── myproject_server/ # Your server: endpoints, models, config, migrations +├── myproject_client/ # Generated client: how your app calls the server +└── myproject_flutter/ # Your Flutter app +``` + +That is the whole mental model: you work in the server and the app, and Serverpod maintains the client between them. Everything else in the workspace supports those three, and the sections below introduce each piece as you need it. + +
+Expand the full workspace tree. +

+ +```text +myproject/ +├── pubspec.yaml # Workspace root: one `dart pub get` resolves all packages +├── AGENTS.md # Instructions for AI agents working in the project +├── .github/ # CI workflows: analyze, format, and test +├── .vscode/ # Attach-to-server debug configs and a serverpod start task +├── .agents/ # Agent skills, plus MCP configs for the editors you picked +├── myproject_server/ # Your server +│ ├── bin/main.dart # Entry point, calls run() in lib/server.dart +│ ├── lib/server.dart # The run() function: creates and starts the server +│ ├── lib/src/greetings/ # Example feature: a model file and an endpoint +│ ├── lib/src/auth/ # Endpoints for the scaffolded email sign-in +│ ├── lib/src/web/ # Routes and widgets for the web server +│ ├── lib/src/generated/ # Generated server code (do not edit) +│ ├── config/ # Run-mode configs, passwords, generator.yaml +│ ├── migrations/ # Database migrations +│ ├── web/ # Static files and pages the web server serves +│ ├── test/integration/ # Endpoint tests and generated test tools +│ └── docker-compose.yaml # Container alternative for the database, plus the test database +├── myproject_client/ # Generated client package +│ └── lib/src/protocol/ # Generated calls and models (do not edit) +└── myproject_flutter/ # Your Flutter app + ├── lib/main.dart # App code: creates the global Client + ├── lib/screens/ # Scaffolded sign-in and greetings screens + ├── lib/driver.dart # Entry point serverpod start uses to launch the app + └── assets/config.json # The server URL the app reads at startup +``` + +The exact set depends on your create-time choices: the auth endpoints and sign-in screen come with authentication, the web pieces with the web server option, and the agent and MCP files with the editors you picked. + +

+
+ +## How the packages relate + +The Flutter app depends on the client package, and the client is how the app reaches the server: it holds a typed method for every endpoint you write. Neither the server nor the client depends on the other; instead, the server's `config/generator.yaml` points at the client package (`client_package_path`), and code generation writes the client's contents directly. + +The workspace is a Dart pub workspace: each package declares `resolution: workspace`, and a single `dart pub get` at the project root resolves all three. + +## Where your code lives, and what is generated + +You write two kinds of source files on the server, and both can live anywhere under the server's `lib/`: + +- **Model files** (`.spy.yaml`) define your serializable classes and database tables. The template keeps them next to the code that uses them, such as `lib/src/greetings/greeting.spy.yaml`. See [Working with models](../data-and-the-database/models). +- **Endpoints** are Dart classes extending `Endpoint`, such as `lib/src/greetings/greeting_endpoint.dart`. Each public method becomes a callable client method: `GreetingEndpoint.hello` is called as `client.greeting.hello(...)`. See [Working with endpoints](../endpoints-and-apis). + +The scaffolded project follows the same pattern beyond the greeting example: `lib/src/auth/` holds the endpoints behind the default email sign-in, and `lib/src/web/` holds the routes the web server serves. + +From those, `serverpod generate` produces the bridge between server and app: + +- On the server, `lib/src/generated/` gets the endpoint dispatch code, the protocol description, and a Dart class per model. +- In the client package, `lib/src/protocol/` gets the `Client` class with its typed endpoint methods, plus the same model classes for the app's side. +- In `test/integration/test_tools/`, the generated [test tools](../testing/get-started). + +Generated code is overwritten on every run, so never edit it; the scaffolded analyzer config excludes it for that reason. While [`serverpod start`](./running-your-server) runs, generation happens automatically when you save; outside a session, run `serverpod generate` yourself. + +## The server entry point + +The server starts in `bin/main.dart`, which only calls the `run` function in `lib/server.dart`. That function creates the server, wires it to your generated code, registers everything that is not an endpoint, and starts it: + +```dart +void run(List args) async { + // Connect the server with your generated code. + final pod = Serverpod(args, Protocol(), Endpoints()); + + // Registrations go here: authentication services and web routes + // in the scaffolded project, and anything else you add. + + // Start the server. + await pod.start(); +} +``` + +Endpoints need no registration: the generated `Endpoints` object passed to the constructor carries them all. Web routes, by contrast, are registered imperatively on `pod.webServer`, which is why the scaffolded `run()` contains route setup. When `pod.start()` runs, the server connects to the database, applies pending migrations when started with `--apply-migrations`, connects to Redis if enabled, brings up its servers, and starts background work such as [future calls](../scheduling/setup) and [health checks](../operations/health-checks). + +## The three servers + +One Serverpod instance runs up to three servers, each on its own port in development: + +- **The API server (8080)** handles incoming endpoint calls from your app. This is the server your generated client talks to. +- **The Insights server (8081)** is a separate, secret-protected server used by Serverpod's tooling. See [Insights](../../tools/insights). +- **The web server (8082)** serves web content: HTML routes, static files, and your built Flutter web app. See [Web server](../web-server/overview). + +The scaffolded development config also reserves port 8090 for the database and 8091 for Redis. + +## The config and migrations directories + +The server's `config/` directory holds one YAML file per [run mode](./configuration#run-modes) (`development`, `test`, `staging`, `production`), the `passwords.yaml` secrets file scaffolded with generated per-environment secrets, and `generator.yaml`, which configures code generation. See [Configuration](./configuration) for all of them. + +The `migrations/` directory starts with one migration that creates your initial schema, and grows as your models change. See [Migrations](../data-and-the-database/database/migrations). + +After the first server start, a gitignored `.serverpod/` directory also appears in the server package: it holds the [embedded database's](./configuration#database-backends) data files, one subdirectory per run mode, created by the server on demand. + +## Editor and agent files + +The workspace ships ready for IDE debugging and AI agents: `.vscode/` contains attach configurations that connect the debugger to a running `serverpod start` session, `AGENTS.md` instructs AI agents on how to work in the project, and, depending on the editors you picked at create time, agent skills are installed under `.agents/` and MCP configuration files register Serverpod's [MCP server](../cli/commands/mcp-server) with your editor. The agent configuration files are excluded from version control by the workspace `.gitignore`. + +## Related + +- [How it works](../../how-it-works): the guided tour of building with Serverpod. +- [Running your server](./running-your-server): the development loop around this project. +- [Configuration](./configuration): every file in `config/` in depth. +- [Working with endpoints](../endpoints-and-apis): writing the API the client calls. +- [Working with models](../data-and-the-database/models): defining your data. diff --git a/docs/06-concepts/01-server-fundamentals/02-running-your-server.md b/docs/06-concepts/01-server-fundamentals/02-running-your-server.md new file mode 100644 index 00000000..a4f29834 --- /dev/null +++ b/docs/06-concepts/01-server-fundamentals/02-running-your-server.md @@ -0,0 +1,86 @@ +--- +description: The serverpod start command runs your project in development, with code generation, hot reload, the database, migrations, and the Flutter app in one terminal. +--- + +# Running your server + +As you build, one command keeps your server, database, generated code, and app in sync, so a change shows up the moment you save. The `serverpod start` command generates the latest code, starts your development database, runs your server with hot reload, and launches your companion Flutter apps, all inside a single interactive terminal. + +Run it from your project's root folder or one of its package folders: + +```bash +serverpod start +``` + +The interactive terminal shows a tab for the server and for each running app, with the most common actions along the bottom. Shortcuts are unshifted key presses: **M** means typing a lowercase `m`, while **Shift+M** produces the capital and triggers the variant. Press **H** for the full list of shortcuts, and **Q** to quit the session. If a session is already running for the project, a second `serverpod start` tells you so and exits. While the session runs, it also exposes an MCP endpoint that AI agents can use to drive it. See the [`serverpod mcp-server` reference](../cli/commands/mcp-server). + +New projects use an embedded PostgreSQL database that the server manages for you, so there is nothing else to start. See [Database backends](./configuration#database-backends) for how it is configured and how to use an external database instead. + +Use `serverpod start` for local development only. To run your server in production, deploy it instead. See [Deploy to Serverpod Cloud](../../deployments/deploy-to-serverpod-cloud) or [Custom hosting](../../deployments/custom-hosting/choosing-a-strategy). + +## Save a file to hot reload + +By default, `serverpod start` watches your project. Saving a file recompiles and hot reloads the affected code without a restart: endpoints, models, the generated client, web routes, and the running Flutter apps all stay in step as you work. Dependency changes are picked up too, so the session survives a `pub get`. + +The **R** key adapts to the situation. In watch mode, where saves already hot reload, **R** performs a hot restart: use it when a change cannot be hot reloaded, such as code that only runs at startup. If the project has errors instead, the session stays open and tells you what failed; the server boots automatically once a save fixes the errors, or press **R** to retry the build and start. + +To start without watching, pass `--no-watch`. Nothing reloads on save; there, **R** hot reloads on demand, and **Shift+R** restarts the server. + +## Manage migrations from the terminal + +On the first boot of a session, `serverpod start` applies any pending migrations. While it runs, you handle further schema changes from the terminal without leaving the session: + +- **M** creates a migration from your current model changes. +- **A** applies pending migrations to the database. +- **P** creates a repair migration to reconcile a database that has drifted from your migrations. This shortcut is not shown in the bottom bar; press **H** to see it listed. + +Hold **Shift** with **M** or **P** to force the migration: it is created even when there are no changes to record, and even when Serverpod warns that information may be destroyed, so force deliberately. For how migrations work, see [Migrations](../data-and-the-database/database/migrations). + +## Choose a run mode + +By default, `serverpod start` runs in the `development` run mode. To start in another mode, forward a `--mode` argument to the server after `--`: + +```bash +serverpod start -- --mode staging +``` + +The run mode selects which configuration and passwords the server loads. See [Run modes](./configuration#run-modes) for what each mode reads. Flutter apps only launch in the `development` run mode. + +## Run the server on its own + +By default, `serverpod start` also launches the companion Flutter apps marked `auto_launch: true` in the server's `pubspec.yaml`. To start only the server, disable that: + +```bash +serverpod start --no-flutter +``` + +You can still launch an app on demand: press **Ctrl+R** in the terminal to open the app launch panel. + +If your project runs auxiliary services from a `docker-compose.yaml`, such as Redis, pass `--docker` to start them with the session. + +To run without the interactive terminal, pass `--no-tui`. When the output is not a terminal, for example in CI, `serverpod start` falls back to plain output on its own. + +## Run the server directly + +Outside `serverpod start`, the server is a plain Dart program you can run yourself from the server package directory: + +```bash +dart run bin/main.dart --apply-migrations +``` + +The server accepts arguments that control how it starts: `--mode` selects the run mode, `--role` selects the [server role](#choose-a-server-role), and `--apply-migrations` applies pending migrations during startup. Without `--apply-migrations`, the server starts against the schema as it is. See the [run options reference](../lookups/configuration-reference#run-options) for the full list, and the [Deploy](../../deployments/deploy-to-serverpod-cloud) section for running in production. + +## Choose a server role + +In production, the `--role` argument controls which parts of the server run: + +- **`monolith`** (default) runs everything: the API, Insights, and web servers, plus [future calls](../scheduling/setup) and [health checks](../operations/health-checks). +- **`serverless`** serves requests only. Future calls and health checks are disabled, which fits platforms that start and stop instances on demand. +- **`maintenance`** starts no servers. It performs one-shot work, applying migrations when passed `--apply-migrations` and running any due future calls, then exits. The exit code reports success or failure, which makes it fit for CI jobs and scheduled maintenance tasks. + +## Related + +- [`serverpod start` reference](../cli/commands/start): every command-line option. +- [Configuration](./configuration): the run modes and files the server loads on start. +- [Migrations](../data-and-the-database/database/migrations): how schema changes reach the database. +- [Deploy to Serverpod Cloud](../../deployments/deploy-to-serverpod-cloud): run your server in production instead of locally. diff --git a/docs/06-concepts/01-server-fundamentals/02-configuration.md b/docs/06-concepts/01-server-fundamentals/03-configuration.md similarity index 53% rename from docs/06-concepts/01-server-fundamentals/02-configuration.md rename to docs/06-concepts/01-server-fundamentals/03-configuration.md index f225c340..c9f78df2 100644 --- a/docs/06-concepts/01-server-fundamentals/02-configuration.md +++ b/docs/06-concepts/01-server-fundamentals/03-configuration.md @@ -4,9 +4,9 @@ description: Configuration in Serverpod comes from YAML files, environment varia # Configuration -Configuration decides what your server listens on, which database and Redis it connects to, and how it behaves in each run mode, so the same code runs locally, in staging, and in production without edits. Serverpod reads configuration from three sources: environment variables, the `config/.yaml` files, and a `ServerpodConfig` Dart object passed to the `Serverpod` constructor. You can mix them, and each source overrides the ones before it. +Configuration decides what your server listens on, which database and Redis (an in-memory store Serverpod can use for pub/sub and caching) it connects to, and how it behaves in each run mode, so the same code runs locally, in staging, and in production without edits. Serverpod reads configuration from three sources: the `config/.yaml` files, environment variables, and a `ServerpodConfig` Dart object passed to the `Serverpod` constructor. You can mix them, and each source overrides the ones before it. -The only settings you must provide are for the API server. With no configuration at all, Serverpod uses its built-in defaults. +With no configuration at all, Serverpod falls back to built-in defaults, so you can start with nothing and add configuration as you need it. ## How configuration works @@ -18,17 +18,42 @@ The three sources apply in order of precedence. The YAML files are the baseline, For every available option, its environment variable, config-file key, and default, see the [Configuration reference](../lookups/configuration-reference). -## Configuration files +### Defaults -Name each config file after the run mode you start the server in and place it in the `config` directory at the root of the server project. For example, `config/development.yaml` is used when running in the `development` run mode. +If no YAML config files exist, no environment variables are configured, and no Dart config is supplied, the server runs with this built-in default: the API server on port 8080 at `localhost`. -```yaml +```dart +ServerpodConfig( + apiServer: ServerConfig( + port: 8080, + publicHost: 'localhost', + publicPort: 8080, + publicScheme: 'http', + ), +); +``` + +## Run modes + +The server always runs in one of four run modes: `development` (the default), `test`, `staging`, or `production`. The run mode is selected with the `--mode` argument when the server starts, and it decides what the server loads: + +- The matching `config/.yaml` file. +- The matching section of the [passwords file](#manage-secrets), merged with its `shared` section. + +The `test` mode is used by the [test tools](../testing/get-started), which start the server against `config/test.yaml`. The other modes separate your local setup from your deployed environments. See [Running your server](./running-your-server#choose-a-run-mode) for how to pass `--mode` through `serverpod start`. + +Run modes configure the server side. Your Flutter app picks the matching server address per environment on its own; see [Point the client at each environment](../endpoints-and-apis#point-the-client-at-each-environment). + +## Configure with YAML files + +The `config` directory at the root of the server project holds one file per run mode, created with your project. The server loads the file named after the run mode it starts in: `config/development.yaml` is used when running in the `development` run mode. This is the scaffolded development file for a project named `myproject`, with comments and optional keys removed: + +```yaml title="config/development.yaml" apiServer: port: 8080 publicHost: localhost publicPort: 8080 publicScheme: http - websocketPingInterval: 30 insightsServer: port: 8081 @@ -45,9 +70,9 @@ webServer: database: host: localhost port: 8090 - name: database_name + name: myproject user: postgres - maxConnectionCount: 10 + dataPath: .serverpod/development/pgdata redis: enabled: false @@ -58,29 +83,24 @@ maxRequestSize: 524288 sessionLogs: persistentEnabled: true - cleanupInterval: 24h - retentionPeriod: 90d - retentionCount: 100000 consoleEnabled: true - consoleLogFormat: json - -futureCallExecutionEnabled: true - -futureCall: - concurrencyLimit: 1 - scanInterval: 5000 + consoleLogFormat: text ``` +The three server blocks configure Serverpod's three servers: the API server your app talks to, the [Insights](../../tools/insights) server used by Serverpod's tooling, and the [web server](../web-server/overview) for serving web content. The `sessionLogs` block controls how session logs are stored and printed; see [Logging](../operations/logging). Keys not in the scaffolded file cover future calls, websocket ping intervals, and more; see the [Configuration reference](../lookups/configuration-reference) for the full list with defaults. + ### Database backends Serverpod supports both PostgreSQL and SQLite as database backends. :::warning -The same database backend must be used for all run modes. Otherwise, an error will be thrown when generating migrations. This practice is recommended to ensure that the development environment is consistent with the production environment. +All run modes must use the same database backend: creating migrations fails otherwise. This also keeps your development environment consistent with production. ::: #### PostgreSQL +New projects run an embedded PostgreSQL in the `development` and `test` run modes. When `dataPath` is set, the server boots and manages a PostgreSQL in that directory before connecting, so there is no separate database to install or start. The embedded database is for local development and testing only; in production, connect to an external PostgreSQL by omitting `dataPath`: + ```yaml database: host: localhost @@ -99,11 +119,11 @@ database: filePath: server.db ``` -No database password is required when using SQLite. +No database password is required when using SQLite. Persistent session logs are not supported on SQLite: the server keeps console logging and warns if persistent logging is enabled. ## Configure in Dart -To configure Serverpod in Dart, pass an instance of the `ServerpodConfig` class to the `Serverpod` constructor. This config overrides 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. +To configure Serverpod in Dart, pass an instance of the `ServerpodConfig` class to the `Serverpod` constructor, normally inside the `run` function in your `server.dart` file. When you configure this way, `apiServer` is the one field you must provide. ```dart Serverpod( @@ -133,53 +153,12 @@ Serverpod( ); ``` -### Default configuration - -If no YAML config files exist, no environment variables are configured, and no Dart config is supplied, this default configuration is used. - -```dart -ServerpodConfig( - apiServer: ServerConfig( - port: 8080, - publicHost: 'localhost', - publicPort: 8080, - publicScheme: 'http', - ), -); -``` - -## Secrets - -Secrets are declared in the `passwords.yaml` file. Serverpod's API reads them with `getPassword`, so this page uses *secret* and *password* interchangeably. 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](#via-environment-variables). +## Manage secrets -### 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 - -For secrets related to first-party Serverpod packages, see their respective documentation: - -- **Cloud storage**: see [Uploading files](../endpoints-and-apis/file-uploads) for Google Cloud Storage, AWS S3, and Cloudflare R2 secrets. -- **Authentication**: see [Storing Secrets](../authentication/setup#storing-secrets) on the Authentication setup page. +Secrets are declared in the `config/passwords.yaml` file. Serverpod's API reads them with `getPassword`, so this page uses *secret* and *password* interchangeably. The file has a `shared` section, applied in all run modes, and one section per run mode: -### Custom secrets - -You can define your own custom secrets in two ways. - -#### Via the 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 +```yaml title="config/passwords.yaml" shared: - myCustomSharedSecret: 'secret_key' stripeApiKey: 'sk_test_123...' development: @@ -195,15 +174,34 @@ production: twilioApiKey: 'prod_twilio_key' ``` -#### Via environment variables +You can also provide any secret through [environment variables](#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. +### Built-in secrets -| 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. | +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 run-mode or `shared` section of the passwords file. They are separate from any custom secrets you define. -To define a custom password through an environment variable: +| 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 characters. | +| SERVERPOD_PASSWORD_redis | redis | - | The password for the Redis server. | + +Each built-in secret also has a dedicated environment variable: `SERVERPOD_DATABASE_PASSWORD`, `SERVERPOD_SERVICE_SECRET`, and `SERVERPOD_REDIS_PASSWORD`. All environment variables override the passwords file, and the `SERVERPOD_PASSWORD_*` form wins when both are set. + +### Secrets for first-party packages + +For secrets related to first-party Serverpod packages, see their respective documentation: + +- **Cloud storage**: see [Uploading files](../endpoints-and-apis/file-uploads) for Google Cloud Storage, AWS S3, and Cloudflare R2 secrets. +- **Authentication**: see [Storing Secrets](../authentication/setup#storing-secrets) on the Authentication setup page. + +### Custom secrets + +Add your own keys to the passwords file the same way, under `shared` or a run-mode section, as `stripeApiKey` and `twilioApiKey` are in the example above. + +#### Via environment variables + +You can also define custom secrets using environment variables with the `SERVERPOD_PASSWORD_` prefix. For example, `SERVERPOD_PASSWORD_myApiKey` becomes available as `myApiKey`: the prefix is stripped. These variables override same-named entries in the passwords file and, like the `shared` section, apply in all run modes. ```bash export SERVERPOD_PASSWORD_stripeApiKey=sk_test_123... @@ -241,13 +239,7 @@ In production, set secrets through `SERVERPOD_PASSWORD_*` environment variables, ### Passwords on Serverpod Cloud -On [Serverpod Cloud](/cloud), the values you read with `getPassword` live in the **Passwords** tier. Set them from the command line instead of editing a passwords file: - -```bash -scloud password set stripeApiKey "sk_live_..." -``` - -Use `--from-file` for long or multi-line values such as a service account JSON. Cloud stores each password encrypted and injects it so `getPassword` reads it exactly as it does locally. See [Passwords, secrets, and environment variables](/cloud/concepts/passwords-secrets-env-vars) for the full reference. +On [Serverpod Cloud](/cloud), you set the values that `getPassword` reads from the command line, with `scloud password set`, instead of editing a passwords file. See [Passwords, secrets, and environment variables](/cloud/concepts/passwords-secrets-env-vars) for the full reference. ## Configure code generation @@ -259,9 +251,9 @@ For every `generator.yaml` option, its type and default, see the [Configuration 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 +- **server**: A standard Serverpod application (default). +- **module**: A reusable module that can be imported by other Serverpod projects. +- **internal**: Used only by Serverpod's own framework packages; you will not use this. For modules, you can also specify a `nickname`: @@ -280,14 +272,13 @@ 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: +Fresh projects include this line in `generator.yaml`, which generates the integration test tools: ```yaml -# Remove or comment out this line to disable test tools -# server_test_tools_path: test/integration/test_tools +server_test_tools_path: test/integration/test_tools ``` -See the [testing documentation](../testing/get-started) for more details. +Delete the line to stop generating test tools. See the [testing documentation](../testing/get-started) for how the test tools are used. ### Module dependencies @@ -301,7 +292,7 @@ modules: nickname: custom ``` -This allows you to reference module classes as `module:auth:AuthUser` in your model files. See the [modules documentation](modules) for more information. +This allows you to reference module classes as `module:auth:AuthUser` in your model files. See the [modules documentation](./modules) for more information. ### Shared packages @@ -333,20 +324,29 @@ Control which Serverpod features are enabled: ```yaml features: - database: false # Disables database features + database: false ``` +A server that does not use a database can set `database: false` to skip migrations and table generation. + ### Experimental features -Enable experimental features that are still in development: +No experimental features are available in the current version. The `experimental_features` key is how you opt in when they exist; `all` enables every available one: ```yaml experimental_features: - all: true # Enables all available experimental features + all: true ``` -The `all` key opts into every available experimental feature. No experimental features are available in the current version. See the [experimental features documentation](../operations/experimental-features) for details. +See the [experimental features documentation](../operations/experimental-features) for details. :::warning Experimental features may change or be removed in future versions. ::: + +## Related + +- [Configuration reference](../lookups/configuration-reference): every option with its environment variable, config key, and default. +- [Running your server](./running-your-server): how the server starts and how `--mode` is passed. +- [Database connection](../data-and-the-database/database/connection): connecting to your database in depth. +- [Configure HTTP calls](../endpoints-and-apis/configure-http-calls): the API server's response headers and CORS defaults. diff --git a/docs/06-concepts/01-server-fundamentals/03-modules.md b/docs/06-concepts/01-server-fundamentals/03-modules.md deleted file mode 100644 index c2d11031..00000000 --- a/docs/06-concepts/01-server-fundamentals/03-modules.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -description: Serverpod modules are reusable packages that bundle server, client, and Flutter code with their own endpoints and database tables. ---- - -# Modules - -Serverpod is built around the concept of modules. A Serverpod module is similar to a Dart package but contains both server, client, and Flutter code. A module contains its own namespace for endpoints and methods to minimize the risk of conflicts. - -Examples of modules are the `serverpod_auth_core` and `serverpod_auth_idp` modules, which both are maintained by the Serverpod team. - -## Adding a module to your project - -### Server setup - -To add a module to your project, you must include the server and client/Flutter packages in your project's `pubspec.yaml` files. - -For example, to add the `serverpod_auth_idp` module to your project, you need to add `serverpod_auth_idp_server` to your server's `pubspec.yaml`: - -```yaml -dependencies: - serverpod_auth_idp_server: ^3.x.x -``` - -:::info -Make sure to replace `3.x.x` with the Serverpod version you are using. Serverpod uses the same version number for all official packages. If you use the same version, you will be sure that everything works together. -::: - -In your `config/generator.yaml` you can optionally add the `serverpod_auth_idp` module and give it a `nickname`. The nickname will determine how you reference the module from the client. If the module isn't added in the `generator.yaml`, the default nickname for the module will be used. - -```yaml -modules: - serverpod_auth_idp: - nickname: auth -``` - -See [Configuration](configuration#module-dependencies) for the full set of `generator.yaml` module options. - -Then run `pub get` from your server's directory (e.g., `mypod_server`): - -```bash -$ dart pub get -``` - -Start the server to wire up the module: - -```bash -$ serverpod start -``` - -The module adds tables to your database, so create and apply a migration: in the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it. - -### Client setup - -In your client's `pubspec.yaml`, you will need to add the generated client code from the module. - -```yaml -dependencies: - serverpod_auth_idp_client: ^3.x.x -``` - -### Flutter app setup - -In your Flutter app, add the corresponding dart or Flutter package(s) to your `pubspec.yaml`. - -```yaml -dependencies: - serverpod_auth_idp_flutter: ^3.x.x -``` - -## Referencing a module - -It can be useful to reference serializable objects in other modules from the YAML-files in your models. You do this by adding the module prefix, followed by the nickname of the package. For instance, this is how you reference a serializable class in the `serverpod_auth_idp` package. - -```yaml -class: MyClass -fields: - # Using the full module name - userInfo: module:serverpod_auth_idp:AuthUser - # Or using the nickname - userInfo: module:auth:AuthUser -``` - -## Creating custom modules - -With the `serverpod create` command, it is possible to create new modules for code that is shared between projects or that you want to publish to pub.dev. To create a module instead of a server project, pass `module` to the `--template` flag. - -```bash -$ serverpod create --template module my_module -``` - -The create command will create a server and a client Dart package. If you also want to add custom Flutter code, use `flutter create` to create a package. - -```bash -$ flutter create --template package my_module_flutter -``` - -In your Flutter package, you most likely want to import the client libraries created by `serverpod create`. - -:::info -Most modules will need a set of database tables to function. When naming the tables, you should use the module name as a prefix to the table name to avoid any conflicts. For instance, the Serverpod tables are prefixed with `serverpod_`. -::: diff --git a/docs/06-concepts/01-server-fundamentals/04-modules.md b/docs/06-concepts/01-server-fundamentals/04-modules.md new file mode 100644 index 00000000..6b85ddbe --- /dev/null +++ b/docs/06-concepts/01-server-fundamentals/04-modules.md @@ -0,0 +1,116 @@ +--- +description: Serverpod modules are reusable packages that bundle server, client, and Flutter code with their own endpoints and database tables. +--- + +# Modules + +Modules let you drop ready-made features into your server, such as authentication, or package your own server and app code for reuse across projects and on pub.dev. A module is similar to a Dart package but bundles server code, generated client code, and Flutter widgets, along with its own endpoints and database tables. Each module has its own namespace for endpoints and methods to minimize the risk of conflicts. + +The `serverpod_auth_core` and `serverpod_auth_idp` modules, both maintained by the Serverpod team, are examples: they add complete user authentication to your project. + +## Add a module to your project + +A module ships as one package per part of your project, so you add it to each `pubspec.yaml` that uses it. + +### Add the server package + +To add the `serverpod_auth_idp` module, add `serverpod_auth_idp_server` to your server's `pubspec.yaml`: + +```yaml title="myproject_server/pubspec.yaml" +dependencies: + serverpod_auth_idp_server: 4.0.0-beta.0 +``` + +:::info +Match the version to the Serverpod version you are using; all official packages share the same version number, so matching versions work together. Prerelease versions must be pinned exactly, as above; from a stable release on, a caret constraint such as `^4.0.0` works. +::: + +In your `config/generator.yaml`, you can optionally list the module and give it a `nickname`, which sets how you [reference the module's models](#reference-a-module-in-your-models). Without an entry, the module's own declared nickname is used; for the official modules that is the full package name. + +```yaml +modules: + serverpod_auth_idp: + nickname: idp +``` + +See [Configuration](./configuration#module-dependencies) for the full set of `generator.yaml` module options. + +Then fetch dependencies; one `dart pub get` anywhere in the workspace resolves every package: + +```bash +dart pub get +``` + +Start the server, which regenerates your code so the module's endpoints and models become part of your server and client: + +```bash +serverpod start +``` + +The module adds tables to your database, so create and apply a migration: in the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it. + +### Add the client package + +In your client's `pubspec.yaml`, add the module's generated client package: + +```yaml title="myproject_client/pubspec.yaml" +dependencies: + serverpod_auth_idp_client: 4.0.0-beta.0 +``` + +### Add the Flutter package + +In your Flutter app's `pubspec.yaml`, add the module's Flutter package: + +```yaml title="myproject_flutter/pubspec.yaml" +dependencies: + serverpod_auth_idp_flutter: 4.0.0-beta.0 +``` + +## Reference a module in your models + +You can reference a module's serializable classes from the model files in your project by adding the `module:` prefix, followed by the module's nickname. A module has exactly one effective nickname: the one you set in your `generator.yaml`, or, if you set none, the module's own declared nickname. For the official modules, the declared nickname is the full package name. + +With `nickname: auth` set for `serverpod_auth_core` in your `generator.yaml`, reference its `AuthUser` class as: + +```yaml +class: MyClass +fields: + userInfo: module:auth:AuthUser +``` + +With no `generator.yaml` entry, use the module's declared nickname instead: + +```yaml +class: MyClass +fields: + userInfo: module:serverpod_auth_core:AuthUser +``` + +Setting your own nickname replaces the declared one, so only one of these forms works at a time. + +See [Working with models](../data-and-the-database/models) for how model files work. + +## Create your own module + +With the `serverpod create` command, you can create your own module for code that is shared between projects or that you want to publish to pub.dev. To create a module instead of a server project, pass `module` to the `--template` flag: + +```bash +serverpod create --template module my_module +``` + +The command creates a server and a client Dart package. If you also want to ship Flutter code, create a package for it with Flutter: + +```bash +flutter create --template package my_module_flutter +``` + +In the Flutter package, import the client libraries that `serverpod create` generated. + +If your module needs database tables, prefix their names with the module name to avoid conflicts with the projects that use it. Serverpod's own tables are prefixed with `serverpod_`. + +## Related + +- [Configuration](./configuration#module-dependencies): every `generator.yaml` module option. +- [Authentication](../authentication/get-started): the auth modules in practice. +- [`serverpod create` reference](../cli/commands/create): all create templates and flags. diff --git a/docs/06-concepts/02-endpoints-and-apis/01-working-with-endpoints.md b/docs/06-concepts/02-endpoints-and-apis/01-working-with-endpoints.md index ae970d7b..49c4bc87 100644 --- a/docs/06-concepts/02-endpoints-and-apis/01-working-with-endpoints.md +++ b/docs/06-concepts/02-endpoints-and-apis/01-working-with-endpoints.md @@ -28,11 +28,11 @@ class ExampleEndpoint extends Endpoint { } ``` -The above code will create an endpoint called `example` (the Endpoint suffix will be removed) with the single `hello` method. To generate the client-side code run `serverpod generate` in the home directory of the server. +The above code will create an endpoint called `example` (the Endpoint suffix will be removed) with the single `hello` method. While [`serverpod start`](./server-fundamentals/running-your-server) is running, the client-side code is generated automatically when you save. Outside a session, run `serverpod generate` in the server directory instead. :::info -You can pass the `--watch` flag to `serverpod generate` to watch for changed files and generate code whenever your source files are updated. This is useful during the development of your server. +You can pass the `--watch` flag to `serverpod generate` to watch for changed files and regenerate without a `serverpod start` session. ::: @@ -58,7 +58,7 @@ var client = Client('http://localhost:8080/') If you run the app in an Android emulator, use `10.0.2.2` instead of `localhost`, since `10.0.2.2` is the IP address of the host machine from inside the emulator. To access the server from a different device on the same network (such as a physical phone), replace `localhost` with the local IP address of your machine. You can find the local IP by running `ifconfig` (Linux/macOS) or `ipconfig` (Windows). -Make sure to also update the `publicHost` in the development config so the server always serves the client with the correct path to assets and other resources. +Make sure to also update the `publicHost` in the development config so the server always serves the client with the correct path to assets and other resources. See [Configuration](./server-fundamentals/configuration) for how the config files work. ```yaml # your_project_server/config/development.yaml diff --git a/docs/06-concepts/02-endpoints-and-apis/07-streaming.md b/docs/06-concepts/02-endpoints-and-apis/07-streaming.md index 6ce3a827..27d700e2 100644 --- a/docs/06-concepts/02-endpoints-and-apis/07-streaming.md +++ b/docs/06-concepts/02-endpoints-and-apis/07-streaming.md @@ -87,7 +87,7 @@ For more details on handling revoked authentication, refer to the section on [ha The server sends periodic ping messages on open streaming connections to keep them alive. The interval between pings is configurable and defaults to 30 seconds. -If you deploy behind a load balancer or proxy with a shorter idle timeout (for example, 15-20 seconds), you may need to lower the ping interval so connections are not closed. Set the `SERVERPOD_WEBSOCKET_PING_INTERVAL` environment variable to the desired interval in seconds, or configure `websocketPingInterval` in your [configuration](../server-fundamentals/configuration) file. +If you deploy behind a load balancer or proxy with a shorter idle timeout (for example, 15-20 seconds), you may need to lower the ping interval so connections are not closed. Set the `SERVERPOD_WEBSOCKET_PING_INTERVAL` environment variable to the desired interval in seconds, or configure `websocketPingInterval` in your config file; see the [Configuration reference](../lookups/configuration-reference). ### Error handling diff --git a/docs/06-concepts/06-scheduling/04-configuration.md b/docs/06-concepts/06-scheduling/04-configuration.md index 6814294d..8fc9c021 100644 --- a/docs/06-concepts/06-scheduling/04-configuration.md +++ b/docs/06-concepts/06-scheduling/04-configuration.md @@ -4,7 +4,7 @@ description: Future call configuration in Serverpod sets concurrency limits, the # Configuration -Future calls can be configured using options defined in the configuration files or environment variables. For a detailed list of configuration options, refer to the [Configuration](../server-fundamentals/configuration) page. +Future calls can be configured using options defined in the configuration files or environment variables. For a detailed list of configuration options, refer to the [Configuration reference](../lookups/configuration-reference). ```yaml futureCallExecutionEnabled: true diff --git a/docs/06-concepts/07-operations/02-logging.md b/docs/06-concepts/07-operations/02-logging.md index 047b09b9..8273b5a0 100644 --- a/docs/06-concepts/07-operations/02-logging.md +++ b/docs/06-concepts/07-operations/02-logging.md @@ -36,7 +36,7 @@ For the default values when environment variables are not set, see the [default - `SERVERPOD_SESSION_LOG_RETENTION_PERIOD`: How long to keep session log entries (duration string, e.g. `30d`, `6h`). Set to empty or omit to use the default (90 days). - `SERVERPOD_SESSION_LOG_RETENTION_COUNT`: Maximum number of session log entries to keep. Set to empty or omit to use the default (100,000). - `SERVERPOD_SESSION_CONSOLE_LOG_ENABLED`: Controls whether session logs are output to the console. -- `SERVERPOD_SESSION_CONSOLE_LOG_FORMAT`: The format for console logging (`text` or `json`). See [configuration](../server-fundamentals/configuration). +- `SERVERPOD_SESSION_CONSOLE_LOG_FORMAT`: The format for console logging (`text` or `json`). See the [Configuration reference](../lookups/configuration-reference). ### Configuration file example @@ -60,7 +60,7 @@ By default, session logging behavior depends on whether the project has database - **When a database is present** - `persistentEnabled` is set to `true`, meaning logs are stored in the database. - - `consoleEnabled` is set to `false` by default, meaning logs are not printed to the console unless explicitly enabled. + - `consoleEnabled` defaults to `true` in the `development` run mode and `false` in the other run modes, so local runs print to the console while deployed runs rely on the database logs unless console logging is explicitly enabled. - **When no database is present** diff --git a/docs/06-concepts/lookups/configuration-reference.md b/docs/06-concepts/lookups/configuration-reference.md index 336b4357..f050cf10 100644 --- a/docs/06-concepts/lookups/configuration-reference.md +++ b/docs/06-concepts/lookups/configuration-reference.md @@ -4,7 +4,7 @@ description: Every Serverpod configuration option, covering run settings, server # Configuration reference -Every configuration option Serverpod's core library reads. Options come from three sources: environment variables, the `config/.yaml` files, and the `ServerpodConfig` Dart object. Environment variables override the YAML files, and the Dart object overrides both. For how to choose between them, see [Configuration](../server-fundamentals/configuration). +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, and the Dart object overrides both. For how to choose between them, see [Configuration](../server-fundamentals/configuration). ## Run options @@ -21,7 +21,7 @@ Set the run mode, server role, and boot behavior. Declare each per run mode in t ## Server and services -Ports, hosts, and connection settings for the API, Insights, and web servers, the database, Redis, session logs, and future calls. +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. | Environment variable | Config file | Default | Description | | ----------------------------------------- | ----------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -59,8 +59,8 @@ Ports, hosts, and connection settings for the API, Insights, and web servers, th | SERVERPOD_SESSION_LOG_CLEANUP_INTERVAL | sessionLogs.cleanupInterval | 24h | How often to run the log cleanup job. Duration string (e.g. `24h`, `2d`). Set to null to disable automated purging. | | SERVERPOD_SESSION_LOG_RETENTION_PERIOD | sessionLogs.retentionPeriod | 90d | How long to keep session log entries. Duration string (e.g. `30d`, `60d`). Set to null to disable time-based cleanup. | | SERVERPOD_SESSION_LOG_RETENTION_COUNT | sessionLogs.retentionCount | 100000 | Maximum number of session log entries to keep. Set to null to disable count-based cleanup. | -| 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_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 | @@ -68,6 +68,26 @@ Ports, hosts, and connection settings for the API, Insights, and web servers, th | 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](../operations/experimental-features#exception-monitoring). | + +### Password environment variables + +Secrets are read from `config/passwords.yaml` and can be overridden per secret through environment variables; see [Manage secrets](../server-fundamentals/configuration#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*<name> | 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`.