diff --git a/docs/06-concepts/10-modules.md b/docs/06-concepts/10-modules.md index 442b0747..71857e1f 100644 --- a/docs/06-concepts/10-modules.md +++ b/docs/06-concepts/10-modules.md @@ -29,20 +29,20 @@ modules: nickname: auth ``` -Then run `pub get` and `serverpod generate` from your server's directory (e.g., `mypod_server`) to add the module to your project's deserializer. +Then run `pub get` from your server's directory (e.g., `mypod_server`): ```bash $ dart pub get -$ serverpod generate ``` -Finally, since modules might include modifications to the database schema, you should create a new database migration and apply it by running `serverpod create-migration` then `dart bin/main.dart --apply-migrations` from your server's directory. +Start the server to wire up the module: ```bash -$ serverpod create-migration -$ dart bin/main.dart --apply-migrations +$ 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. diff --git a/docs/06-concepts/11-authentication/01-setup.md b/docs/06-concepts/11-authentication/01-setup.md index 2413526a..0b65c237 100644 --- a/docs/06-concepts/11-authentication/01-setup.md +++ b/docs/06-concepts/11-authentication/01-setup.md @@ -112,24 +112,13 @@ By default, endpoints for all providers are disabled. To enable a provider, it i class EmailIdpEndpoint extends EmailIdpBaseEndpoint {} ``` -3. Run `serverpod generate` to generate the client code and endpoint methods for the provider. +3. Start the server with `serverpod start`. It generates the client code and endpoint methods for the provider, then runs the server with hot reload. ```bash - $ serverpod generate + $ serverpod start ``` -4. Create a migration to initialize the database for the provider. - - ```bash - # Create the migration - $ serverpod create-migration - - # Start the database container - $ docker compose up --build --detach - - # Apply the migration - $ dart run bin/main.dart --role maintenance --apply-migrations - ``` +4. Create and apply the migration that initializes the database for the provider. In the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it. :::info If this is the first time creating migrations after adding the module, besides the provider tables, all auth module tables will also be created. More detailed migration instructions can be found in the [migration guide](../database/migrations). diff --git a/docs/06-concepts/11-authentication/04-providers/01-anonymous/01-setup.md b/docs/06-concepts/11-authentication/04-providers/01-anonymous/01-setup.md index e9e3f86c..c9cecff7 100644 --- a/docs/06-concepts/11-authentication/04-providers/01-anonymous/01-setup.md +++ b/docs/06-concepts/11-authentication/04-providers/01-anonymous/01-setup.md @@ -48,7 +48,7 @@ import 'package:serverpod_auth_idp_server/providers/anonymous.dart'; class AnonymousIdpEndpoint extends AnonymousIdpBaseEndpoint {} ``` -Then, run `serverpod generate` to generate the client code and create a migration to initialize the database for the provider. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). +Then, start the server with `serverpod start` to generate the client code, then create and apply the migration that initializes the database for the provider (in the `serverpod start` terminal, press **M**, then **A**). More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). ### Basic configuration options diff --git a/docs/06-concepts/11-authentication/04-providers/02-email/01-setup.md b/docs/06-concepts/11-authentication/04-providers/02-email/01-setup.md index fdaabc57..4aa91905 100644 --- a/docs/06-concepts/11-authentication/04-providers/02-email/01-setup.md +++ b/docs/06-concepts/11-authentication/04-providers/02-email/01-setup.md @@ -76,7 +76,7 @@ import 'package:serverpod_auth_idp_server/providers/email.dart'; class EmailIdpEndpoint extends EmailIdpBaseEndpoint {} ``` -Then, run `serverpod generate` to generate the client code and create a migration to initialize the database for the provider. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). +Then, start the server with `serverpod start` to generate the client code, then create and apply the migration that initializes the database for the provider (in the `serverpod start` terminal, press **M**, then **A**). More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). ### Basic configuration options diff --git a/docs/06-concepts/11-authentication/04-providers/03-google/01-setup.md b/docs/06-concepts/11-authentication/04-providers/03-google/01-setup.md index b9c4b2c3..32fe440d 100644 --- a/docs/06-concepts/11-authentication/04-providers/03-google/01-setup.md +++ b/docs/06-concepts/11-authentication/04-providers/03-google/01-setup.md @@ -145,16 +145,16 @@ import 'package:serverpod_auth_idp_server/providers/google.dart'; class GoogleIdpEndpoint extends GoogleIdpBaseEndpoint {} ``` -### Generate code and apply migrations +### Start the server -Run the following commands from your server project directory (e.g., `my_project_server/`) to generate client code and apply the database migration: +Start the server from your server project directory (e.g., `my_project_server/`): ```bash -serverpod generate -serverpod create-migration -dart run bin/main.dart --apply-migrations +serverpod start ``` +Then create and apply the migration for the provider's tables: in the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it. + :::warning Skipping the migration will cause the server to crash at runtime when the Google provider tries to read or write user data. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). ::: @@ -244,7 +244,7 @@ On web, Google completes sign-in by redirecting the browser to a callback URL yo ```bash flutter build web --output ../my_project_server/web/app # from your Flutter project -dart run bin/main.dart # from your server project +serverpod start # from your server project ``` Open `http://localhost:8082/app` to test. `flutter run -d chrome` won't work here because Flutter's dev server runs on a different port from Serverpod — for hot-reload workflows, use the [separately-hosted Flutter web](./customizations#separately-hosted-flutter-web) flow instead. @@ -322,7 +322,7 @@ Swap the redirect URI for your production URL when deploying. See [Configuring t ### Show the Google sign-in button -The Serverpod template ships with a `SignInScreen` widget at `lib/screens/sign_in_screen.dart`. It listens to `client.auth.authInfoListenable` and swaps between `SignInWidget` while the user is signed out and the `child` you pass it once they sign in. `SignInWidget` auto-detects which identity provider endpoints are registered on the server, so once `GoogleIdpEndpoint` is exposed and `serverpod generate` has run, the Google button appears inside it. +The Serverpod template ships with a `SignInScreen` widget at `lib/screens/sign_in_screen.dart`. It listens to `client.auth.authInfoListenable` and swaps between `SignInWidget` while the user is signed out and the `child` you pass it once they sign in. `SignInWidget` auto-detects which identity provider endpoints are registered on the server, so once `GoogleIdpEndpoint` is exposed and the client code has been regenerated, the Google button appears inside it. ```dart import 'package:flutter/material.dart'; diff --git a/docs/06-concepts/11-authentication/04-providers/03-google/04-troubleshooting.md b/docs/06-concepts/11-authentication/04-providers/03-google/04-troubleshooting.md index 16a66d25..a661e9e2 100644 --- a/docs/06-concepts/11-authentication/04-providers/03-google/04-troubleshooting.md +++ b/docs/06-concepts/11-authentication/04-providers/03-google/04-troubleshooting.md @@ -21,7 +21,7 @@ Go through this before investigating a specific error. Most problems come from a - [ ] For new or customized servers, confirm auth services and JWT are configured per [Authentication setup](../../setup#identity-providers-configuration) before adding Google. - [ ] Add `GoogleIdpConfigFromPasswords()` to `identityProviderBuilders` in `server.dart`. - [ ] Create a `GoogleIdpEndpoint` file in `lib/src/auth/`. -- [ ] Run `serverpod generate`, then `serverpod create-migration`, then apply migrations using `--apply-migrations`. +- [ ] Start the server with `serverpod start`, then create and apply the migration (press **M**, then **A**). #### Client @@ -167,15 +167,9 @@ Every line of the JSON must be indented by at least one level more than `googleC **Problem:** The server builds and starts, but crashes when a user tries Google sign-in. The error cites a missing table (like `serverpod_auth_idp_google_account`). -**Cause:** `serverpod generate` has been run, but you didn't create or apply the accompanying database migration. +**Cause:** The database migration that creates the provider's tables was never created or applied. -**Resolution:** Create and apply the migration: - -```bash -serverpod generate -serverpod create-migration -dart run bin/main.dart --apply-migrations -``` +**Resolution:** In the running `serverpod start` terminal, press **M** to create the migration, then **A** to apply it. ## Lightweight sign-in (One Tap) not appearing diff --git a/docs/06-concepts/11-authentication/04-providers/04-apple/01-setup.md b/docs/06-concepts/11-authentication/04-providers/04-apple/01-setup.md index b7e24df9..095561aa 100644 --- a/docs/06-concepts/11-authentication/04-providers/04-apple/01-setup.md +++ b/docs/06-concepts/11-authentication/04-providers/04-apple/01-setup.md @@ -166,16 +166,16 @@ import 'package:serverpod_auth_idp_server/providers/apple.dart'; class AppleIdpEndpoint extends AppleIdpBaseEndpoint {} ``` -### Generate code and apply migrations +### Start the server -Run the following commands from your server project directory (e.g., `my_project_server/`) to generate client code and apply the database migration: +Start the server from your server project directory (e.g., `my_project_server/`): ```bash -serverpod generate -serverpod create-migration -dart run bin/main.dart --apply-migrations +serverpod start ``` +Then create and apply the migration for the provider's tables: in the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it. + :::note Skipping the migration will cause the server to crash at runtime when the Apple provider tries to read or write user data. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). ::: diff --git a/docs/06-concepts/11-authentication/04-providers/04-apple/04-troubleshooting.md b/docs/06-concepts/11-authentication/04-providers/04-apple/04-troubleshooting.md index cea085a7..1d49fef4 100644 --- a/docs/06-concepts/11-authentication/04-providers/04-apple/04-troubleshooting.md +++ b/docs/06-concepts/11-authentication/04-providers/04-apple/04-troubleshooting.md @@ -23,7 +23,7 @@ Go through this before investigating a specific error. Most problems come from a * [ ] Add `AppleIdpConfigFromPasswords()` to `identityProviderBuilders` in `server.dart`. * [ ] Call **`pod.configureAppleIdpRoutes(...)`** on the server before the pod starts. * [ ] Create an `AppleIdpEndpoint` file in `lib/src/auth/`. -* [ ] Run **`serverpod generate`**, then apply migrations using `--apply-migrations`. +* [ ] Start the server with `serverpod start`, then create and apply the migration (press **M**, then **A**). #### Client @@ -119,15 +119,9 @@ If you use `--dart-define`, confirm `APPLE_SERVICE_IDENTIFIER` is the Services I **Problem:** The server builds and starts, but crashes when a user tries Apple sign-in. The error cites a missing table (like `serverpod_auth_idp_apple_account`). -**Cause:** `serverpod generate` has been run, but you didn't create or apply the accompanying database migration. +**Cause:** The database migration that creates the provider's tables was never created or applied. -**Resolution:** Create and apply the migration: - -```bash -serverpod generate -serverpod create-migration -dart run bin/main.dart --apply-migrations -``` +**Resolution:** In the running `serverpod start` terminal, press **M** to create the migration, then **A** to apply it. ## Apple rejects the redirect URI with `invalid_request` diff --git a/docs/06-concepts/11-authentication/04-providers/05-facebook/01-setup.md b/docs/06-concepts/11-authentication/04-providers/05-facebook/01-setup.md index 2af2b282..61feb89f 100644 --- a/docs/06-concepts/11-authentication/04-providers/05-facebook/01-setup.md +++ b/docs/06-concepts/11-authentication/04-providers/05-facebook/01-setup.md @@ -141,7 +141,7 @@ class FacebookIdpEndpoint extends FacebookIdpBaseEndpoint {} ### Generate and migrate -Finally, run `serverpod generate` to generate the client code and create a migration to initialize the database for the provider. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). +Finally, start the server with `serverpod start` to generate the client code, then create and apply the migration that initializes the database for the provider (in the `serverpod start` terminal, press **M**, then **A**). More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). ### Basic configuration options diff --git a/docs/06-concepts/11-authentication/04-providers/06-firebase/01-setup.md b/docs/06-concepts/11-authentication/04-providers/06-firebase/01-setup.md index 47bae597..4c9851e5 100644 --- a/docs/06-concepts/11-authentication/04-providers/06-firebase/01-setup.md +++ b/docs/06-concepts/11-authentication/04-providers/06-firebase/01-setup.md @@ -134,16 +134,16 @@ import 'package:serverpod_auth_idp_server/providers/firebase.dart'; class FirebaseIdpEndpoint extends FirebaseIdpBaseEndpoint {} ``` -### 3. Generate code and apply migrations +### 3. Start the server -Run the following commands from your server project directory (e.g., `my_project_server/`) to generate client code and apply the database migration: +Start the server from your server project directory (e.g., `my_project_server/`): ```bash -serverpod generate -serverpod create-migration -dart run bin/main.dart --apply-migrations +serverpod start ``` +Then create and apply the migration for the provider's tables: in the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it. + :::note Skipping the migration will cause the server to crash at runtime when the Firebase provider tries to read or write user data. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). ::: diff --git a/docs/06-concepts/11-authentication/04-providers/06-firebase/05-troubleshooting.md b/docs/06-concepts/11-authentication/04-providers/06-firebase/05-troubleshooting.md index a6ec87fe..6c3336de 100644 --- a/docs/06-concepts/11-authentication/04-providers/06-firebase/05-troubleshooting.md +++ b/docs/06-concepts/11-authentication/04-providers/06-firebase/05-troubleshooting.md @@ -21,7 +21,7 @@ Go through this before investigating a specific error. Most problems come from a - [ ] Confirm the `project_id` inside `firebaseServiceAccountKey` matches the Firebase project the client is using. - [ ] Add `FirebaseIdpConfigFromPasswords()` to `identityProviderBuilders` in `server.dart`. - [ ] Create a `FirebaseIdpEndpoint` file in `lib/src/auth/` extending `FirebaseIdpBaseEndpoint`. -- [ ] Run **`serverpod generate`**, then **`serverpod create-migration`**, then apply migrations with `dart run bin/main.dart --apply-migrations`. +- [ ] Start the server with `serverpod start`, then create and apply the migration (press **M**, then **A**). #### Client @@ -36,15 +36,9 @@ Go through this before investigating a specific error. Most problems come from a **Problem:** The server builds and starts, but crashes when a user tries Firebase sign-in. The error cites a missing table (like `serverpod_auth_idp_firebase_account`). -**Cause:** `serverpod generate` has been run, but you didn't create or apply the accompanying database migration. +**Cause:** The database migration that creates the provider's tables was never created or applied. -**Resolution:** Create and apply the migration: - -```bash -serverpod generate -serverpod create-migration -dart run bin/main.dart --apply-migrations -``` +**Resolution:** In the running `serverpod start` terminal, press **M** to create the migration, then **A** to apply it. ## Token verification fails with "invalid signature" @@ -109,7 +103,7 @@ If you haven't run `flutterfire configure`, do so to generate the `firebase_opti 1. **Missing service account key:** The `firebaseServiceAccountKey` is not present in `passwords.yaml`, or the JSON is invalid. 2. **Missing endpoint:** You did not create the endpoint class extending `FirebaseIdpBaseEndpoint`. Without it, the client has no endpoint to call. -3. **Missing migration:** The provider's database tables don't exist yet. Apply migrations with `dart run bin/main.dart --apply-migrations`. +3. **Missing migration:** The provider's database tables don't exist yet. In the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it. 4. **Project mismatch:** The service account key belongs to a different Firebase project than the one configured in your Flutter app. Compare `project_id` in `firebaseServiceAccountKey` against the project in `firebase_options.dart`. 5. **App Check enabled prematurely:** If you enabled Firebase App Check before the client integration is in place, every request will be rejected with an App Check assertion error. Disable App Check until the client is wired up. diff --git a/docs/06-concepts/11-authentication/04-providers/07-github/01-setup.md b/docs/06-concepts/11-authentication/04-providers/07-github/01-setup.md index 4dc76911..3562df9b 100644 --- a/docs/06-concepts/11-authentication/04-providers/07-github/01-setup.md +++ b/docs/06-concepts/11-authentication/04-providers/07-github/01-setup.md @@ -140,16 +140,16 @@ import 'package:serverpod_auth_idp_server/providers/github.dart'; class GitHubIdpEndpoint extends GitHubIdpBaseEndpoint {} ``` -### Generate code and apply migrations +### Start the server -Run the following commands from your server project directory (e.g., `my_project_server/`) to generate client code and apply the database migration: +Start the server from your server project directory (e.g., `my_project_server/`): ```bash -serverpod generate -serverpod create-migration -dart run bin/main.dart --apply-migrations +serverpod start ``` +Then create and apply the migration for the provider's tables: in the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it. + :::warning Skipping the migration will cause the server to crash at runtime when the GitHub provider tries to read or write user data. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). ::: @@ -271,7 +271,7 @@ To keep these values out of `main.dart` and vary them per build, read them from ### Show the GitHub sign-in button -The Serverpod template ships with a `SignInScreen` widget at `lib/screens/sign_in_screen.dart`. It listens to `client.auth.authInfoListenable` and swaps between `SignInWidget` while the user is signed out and the `child` you pass it once they sign in. `SignInWidget` auto-detects which identity provider endpoints are registered on the server, so once `GitHubIdpEndpoint` is exposed and `serverpod generate` has run, the GitHub button appears inside it. +The Serverpod template ships with a `SignInScreen` widget at `lib/screens/sign_in_screen.dart`. It listens to `client.auth.authInfoListenable` and swaps between `SignInWidget` while the user is signed out and the `child` you pass it once they sign in. `SignInWidget` auto-detects which identity provider endpoints are registered on the server, so once `GitHubIdpEndpoint` is exposed and the client code has been regenerated, the GitHub button appears inside it. To customize the GitHub button or build a fully custom UI, see [Customizing the UI](./customizing-the-ui). diff --git a/docs/06-concepts/11-authentication/04-providers/07-github/04-troubleshooting.md b/docs/06-concepts/11-authentication/04-providers/07-github/04-troubleshooting.md index f1f60777..31420567 100644 --- a/docs/06-concepts/11-authentication/04-providers/07-github/04-troubleshooting.md +++ b/docs/06-concepts/11-authentication/04-providers/07-github/04-troubleshooting.md @@ -20,7 +20,7 @@ Go through this before investigating a specific error. Most problems come from a - [ ] Added `githubClientId` and `githubClientSecret` to `config/passwords.yaml` under the matching environment (`development:` for local, `production:` for prod), or set the matching `SERVERPOD_PASSWORD_githubClientId` and `SERVERPOD_PASSWORD_githubClientSecret` environment variables. - [ ] Added `GitHubIdpConfigFromPasswords()` to `identityProviderBuilders` in `server.dart`. - [ ] Created a `GitHubIdpEndpoint` file in `lib/src/auth/`. -- [ ] Ran `serverpod generate`, then `serverpod create-migration`, then applied migrations with `--apply-migrations`. +- [ ] Started the server with `serverpod start`, then created and applied the migration (pressed **M**, then **A**). #### Client @@ -161,7 +161,7 @@ See [Configuring client IDs on the app](./customizations#configuring-client-ids- **Cause:** The keys are missing from `config/passwords.yaml`, are spelled differently, or are not present under the active environment section. -**Resolution:** Confirm both keys exist under the section matching your run mode (`development:` for `dart run bin/main.dart`, `production:` when deployed): +**Resolution:** Confirm both keys exist under the section matching your run mode (`development:` when running locally with `serverpod start`, `production:` when deployed): ```yaml development: @@ -175,15 +175,9 @@ Quotes are required because the values are strings; YAML interprets unquoted val **Problem:** The server builds and starts, but crashes when a user tries to sign in with GitHub. The error cites a missing table such as `serverpod_auth_idp_github_account`. -**Cause:** `serverpod generate` has been run, but the accompanying database migration was not created or applied. +**Cause:** The database migration that creates the provider's tables was never created or applied. -**Resolution:** Create and apply the migration: - -```bash -serverpod generate -serverpod create-migration -dart run bin/main.dart --apply-migrations -``` +**Resolution:** In the running `serverpod start` terminal, press **M** to create the migration, then **A** to apply it. ## Android sign-in opens GitHub but the callback never fires diff --git a/docs/06-concepts/11-authentication/04-providers/08-microsoft/01-setup.md b/docs/06-concepts/11-authentication/04-providers/08-microsoft/01-setup.md index 86238ee3..ea531dd9 100644 --- a/docs/06-concepts/11-authentication/04-providers/08-microsoft/01-setup.md +++ b/docs/06-concepts/11-authentication/04-providers/08-microsoft/01-setup.md @@ -182,7 +182,7 @@ class MicrosoftIdpEndpoint extends MicrosoftIdpBaseEndpoint {} ### Generate and migrate -Finally, run `serverpod generate` to generate the client code and create a migration to initialize the database for the provider. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). +Finally, start the server with `serverpod start` to generate the client code, then create and apply the migration that initializes the database for the provider (in the `serverpod start` terminal, press **M**, then **A**). More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). ### Basic configuration options diff --git a/docs/06-concepts/11-authentication/04-providers/09-passkey/01-setup.md b/docs/06-concepts/11-authentication/04-providers/09-passkey/01-setup.md index cdc43d4a..9c9b6fa5 100644 --- a/docs/06-concepts/11-authentication/04-providers/09-passkey/01-setup.md +++ b/docs/06-concepts/11-authentication/04-providers/09-passkey/01-setup.md @@ -62,7 +62,7 @@ import 'package:serverpod_auth_idp_server/providers/passkey.dart'; class PasskeyIdpEndpoint extends PasskeyIdpBaseEndpoint {} ``` -Finally, run `serverpod generate` to generate the client code and create a migration to initialize the database for the provider. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). +Finally, start the server with `serverpod start` to generate the client code, then create and apply the migration that initializes the database for the provider (in the `serverpod start` terminal, press **M**, then **A**). More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). ### Basic configuration options