diff --git a/cloud_docs/concepts/deployment-hooks.md b/cloud_docs/concepts/deployment-hooks.md index a2474f0e..74c44c59 100644 --- a/cloud_docs/concepts/deployment-hooks.md +++ b/cloud_docs/concepts/deployment-hooks.md @@ -19,7 +19,7 @@ If your deploy doesn't depend on either, don't add hooks. Deploys work without t ## Configure hooks -Hooks live in `scloud.yaml` under `project.scripts`. Each hook accepts either a single command (string) or a list of commands (array). +Hooks live in `scloud.yaml` under `project.scripts`. Each hook accepts either a single command (string) or a list of commands (array). See the [scloud.yaml schema](/cloud/reference/scloud-yaml-schema#scripts) for the field types and validation rules. Single command: @@ -52,7 +52,7 @@ A non-zero exit code halts further commands in that hook. :::warning -`pre_deploy` and `post_deploy` failures are not symmetric: +The `pre_deploy` and `post_deploy` hooks fail asymmetrically: - A failing `pre_deploy` script aborts the deploy *before* Cloud receives your code. - A failing `post_deploy` script runs *after* the upload, so the deploy has already happened. The `scloud deploy` command exits with an error, but the new version is live. diff --git a/cloud_docs/guides/recover-from-a-failed-deploy.md b/cloud_docs/guides/recover-from-a-failed-deploy.md index e566ce89..214f5097 100644 --- a/cloud_docs/guides/recover-from-a-failed-deploy.md +++ b/cloud_docs/guides/recover-from-a-failed-deploy.md @@ -57,7 +57,7 @@ scloud deployment build-log | grep ERROR Most failed deploys fall into one of these patterns. Match the log output to the closest one. -**Pre-deploy hook failure.** A script in your `scloud.yaml` under `project.scripts.pre_deploy` exited non-zero, so the upload never happened. Run the failing command locally to reproduce, fix the script, commit, and redeploy. See [Deployment hooks](/cloud/concepts/deployment-hooks) for the failure semantics. +**Pre-deploy hook failure.** A script in your `scloud.yaml` under `project.scripts.pre_deploy` exited non-zero, so the upload never happened. Run the failing command locally to reproduce, fix the script, commit, and redeploy. See [Deployment hooks](/cloud/concepts/deployment-hooks) for the failure semantics and the [scloud.yaml schema](/cloud/reference/scloud-yaml-schema#pre_deploy) for the accepted formats. **Upload timeout.** The CLI reports `Send Timeout. Please check your internet connection and try again.` The project never reached Cloud, so nothing was built. Common on first deploys with large project packages or slow connections. Retry with a longer timeout: diff --git a/cloud_docs/reference/cli/_category_.json b/cloud_docs/reference/cli/_category_.json index 6936e2f4..99e72cf9 100644 --- a/cloud_docs/reference/cli/_category_.json +++ b/cloud_docs/reference/cli/_category_.json @@ -1,6 +1,6 @@ { "label": "CLI", "collapsed": true, - "position": 4, + "position": 5, "className": "sidebar-icon-tools" } diff --git a/cloud_docs/reference/project-id-rules.md b/cloud_docs/reference/project-id-rules.md index 5eacf4cc..494c7739 100644 --- a/cloud_docs/reference/project-id-rules.md +++ b/cloud_docs/reference/project-id-rules.md @@ -20,7 +20,7 @@ commands) you will get an error message if the name is not valid. Most `scloud` commands need to know which project to operate on, which can be specified in multiple ways: -- The `scloud.yaml` file in your server package's root directory (see also the [`scloud project link`](/cloud/reference/cli/commands/project/) command) +- The `scloud.yaml` file in your project directory (see [scloud.yaml schema](/cloud/reference/scloud-yaml-schema) for the file format and the [`scloud project link`](/cloud/reference/cli/commands/project/) command for how to generate or update it) - The `-p` / `--project` command line option - The `SERVERPOD_CLOUD_PROJECT_ID` environment variable diff --git a/cloud_docs/reference/scloud-yaml-schema.md b/cloud_docs/reference/scloud-yaml-schema.md new file mode 100644 index 00000000..74dfa63a --- /dev/null +++ b/cloud_docs/reference/scloud-yaml-schema.md @@ -0,0 +1,177 @@ +--- +sidebar_position: 4 +title: scloud.yaml schema +description: "The schema for scloud.yaml: every key, its type, what scloud preserves across commands, and the validation errors you might see." +--- + +# scloud.yaml schema + +A Serverpod project deployed to Serverpod Cloud has a `scloud.yaml` file at its root. The file links the local project to a Cloud project, optionally pins the Dart SDK used for builds, and lists commands to run before or after each deploy. + +Two commands write the file: `scloud launch` creates it on first setup, and `scloud project link` creates or updates it when you link your codebase to a Cloud project. You can also hand-edit it at any time, and scloud preserves your `dartSdk` and hook scripts across later commands. See [How scloud updates the file](#how-scloud-updates-the-file) for the exact per-field rules. + +## File location + +The file lives in your server package directory, alongside the server's `pubspec.yaml`. In a workspace project, that's the `*_server` package directory; in a single-package project, it's the project root. + +To find the file for any subsequent command, scloud searches the starting directory (the current directory, or the value of `--project-dir`) and up to two levels below it. If no `scloud.yaml` is found and the starting directory contains a `pubspec.yaml`, scloud walks one level up and searches with depth 1; this covers single-package projects where you run scloud from a `client/` or `flutter/` subdirectory. Multiple matches throw an ambiguous-search error. With no match, commands that need a project require `-p ` instead. + +When scloud writes the file, it prepends this comment header so the file is recognizable when you open it: + +```yaml +# This file configures your Serverpod Cloud project. +# It is automatically generated and updated by the `scloud` command. +# +# Useful commands: +# - Deploy: `scloud deploy` +# - Get Help: `scloud help` +# +# For full documentation, visit: https://docs.serverpod.dev/cloud +``` + +The header is preserved across subsequent scloud updates. + +## Schema + +One top-level key, `project`, with three fields. + +### projectId + +**Type:** string. **Required.** + +The unique Cloud project identifier the CLI operates on. You set it when you create the project with `scloud launch` or `scloud project create`. See [Project identifier rules](/cloud/reference/project-id-rules) for the naming constraints. + +```yaml title="scloud.yaml" +project: + projectId: "my-app" +``` + +### dartSdk + +**Type:** string. **Optional.** + +Pins the Dart SDK version used for builds. When unset, scloud reads `environment.sdk` from your `pubspec.yaml` and uses the lowest version in the supported range. See [Dart SDK versions](/cloud/reference/dart-sdk-versions) for the supported versions. + +```yaml title="scloud.yaml" +project: + dartSdk: "^3.10.3" +``` + +### scripts + +**Type:** map. **Optional.** + +Holds two hook lists, `pre_deploy` and `post_deploy`. Each runs commands around `scloud deploy`. See [Deployment hooks](/cloud/concepts/deployment-hooks) for when each fires and how failures behave. + +#### pre_deploy + +**Type:** string or list of strings. **Optional.** **Default:** scloud may suggest hooks during `scloud launch` (typically `serverpod generate`). + +Commands that run before scloud uploads your project package. A single string runs one command; a list runs each command in order. Each command runs through the system shell (`bash -c` on macOS and Linux, `cmd /c` on Windows) in your project directory. A non-zero exit code halts further commands and aborts the deploy. + +Single command: + +```yaml title="scloud.yaml" +project: + scripts: + pre_deploy: "serverpod generate" +``` + +Multiple commands: + +```yaml title="scloud.yaml" +project: + scripts: + pre_deploy: + - "serverpod generate" + - "flutter build web" +``` + +#### post_deploy + +**Type:** string or list of strings. **Optional.** **Default:** `[]` (empty list). + +Commands that run after scloud finishes uploading. Same shape and shell semantics as `pre_deploy`. A failure here does not roll back the deploy; the new version is already live by then. + +Empty (the default on a freshly created project): + +```yaml title="scloud.yaml" +project: + scripts: + post_deploy: [] +``` + +Single command: + +```yaml title="scloud.yaml" +project: + scripts: + post_deploy: "curl -X POST https://example.com/notify" +``` + +## Complete example + +A minimal valid file: + +```yaml title="scloud.yaml" +project: + projectId: "my-app" +``` + +What `scloud launch` typically writes for a new project (a suggested `pre_deploy` hook, empty `post_deploy`): + +```yaml title="scloud.yaml" +project: + projectId: "my-app" + dartSdk: "^3.10.3" + scripts: + pre_deploy: + - "serverpod generate" + post_deploy: [] +``` + +## How scloud updates the file + +Both `scloud launch` and `scloud project link` rewrite `scloud.yaml` to reflect the current project. They apply these rules to each field: + +- **`projectId`** is set to the project the command targets. Treat it as scloud-managed; hand-edits won't survive the next run. +- **`dartSdk`** is preserved as you wrote it, unless the command sets a new value. +- **`scripts.pre_deploy`** is merged. Your custom hooks are kept. Hooks that scloud considers "suggested" (for example `serverpod generate` for projects that need it) are re-added on every run, even if you removed them. +- **`scripts.post_deploy`** is preserved entirely. + +In practice, hand-edit `dartSdk` and `post_deploy` freely, and add your own `pre_deploy` hooks alongside any suggested ones. Editing `projectId` by hand has no lasting effect; use `scloud project link` to change which project the file points at. + +## Validation errors + +scloud parses `scloud.yaml` on every command that needs project context. Validation failures raise `SchemaValidationException` in one of three forms. + +### Missing required field + +```text +Missing required key: "project.projectId" +``` + +The required `projectId` field is absent. Add it, or run `scloud project link ` to set it for you. + +### Wrong type for a field + +```text +At path "project.projectId": Expected String, got int +``` + +A field's value is the wrong type. The path tells you which field; the expected and actual types tell you what to change. + +### Wrong format for a script field + +```text +At path "project.scripts.pre_deploy": Expected one of String, [String] +``` + +The `pre_deploy` or `post_deploy` value is neither a string nor a list of strings. Change it to either form (see [`pre_deploy`](#pre_deploy) for examples). + +## Related + +- [Project identifier rules](/cloud/reference/project-id-rules) +- [Dart SDK versions](/cloud/reference/dart-sdk-versions) +- [Deployment hooks](/cloud/concepts/deployment-hooks) +- [scloud project](/cloud/reference/cli/commands/project)