From 0882dba735e49e062c982d4cd3ea057b59c76122 Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Thu, 4 Jun 2026 13:05:41 +0100 Subject: [PATCH 1/3] docs(cloud): Add Deployments concept page, redirect old reference --- cloud_docs/01-getting-started/02-launch.md | 16 +- cloud_docs/02-concepts/01-deployments.md | 154 ++++++++++++++ cloud_docs/02-concepts/_category_.json | 6 + cloud_docs/02-guides/_category_.json | 1 + .../01-deploying-your-application.md | 193 ------------------ .../01-deployment/04-deployment-hooks.md | 2 +- .../01-deployment/05-dart-sdk-versions.md | 2 +- cloud_docs/reference/_category_.json | 2 +- docusaurus.config.js | 5 + 9 files changed, 170 insertions(+), 211 deletions(-) create mode 100644 cloud_docs/02-concepts/01-deployments.md create mode 100644 cloud_docs/02-concepts/_category_.json delete mode 100644 cloud_docs/reference/01-deployment/01-deploying-your-application.md diff --git a/cloud_docs/01-getting-started/02-launch.md b/cloud_docs/01-getting-started/02-launch.md index 2dd6144f..e2ffbae2 100644 --- a/cloud_docs/01-getting-started/02-launch.md +++ b/cloud_docs/01-getting-started/02-launch.md @@ -51,18 +51,4 @@ scloud deployment show The command prints information about your deployment and its status. Once the deployment completes successfully, your Serverpod server will be running on Serverpod Cloud. -## Deploy updates - -After making changes to your project, redeploy it with: - -```bash -scloud deploy -``` - -This command builds the updated server and deploys the new version to Serverpod Cloud. - -:::tip - -If you are deploying a Flutter web app together with your server APIs, make sure to update the version in your Flutter app's `pubspec.yaml`. Otherwise, an old version of the web app may be cached by the user's browser. - -::: +For subsequent deploys, status checks, and the rest of the deploy lifecycle, see the [Deployments](/cloud/concepts/deployments) concept page. diff --git a/cloud_docs/02-concepts/01-deployments.md b/cloud_docs/02-concepts/01-deployments.md new file mode 100644 index 00000000..d162784a --- /dev/null +++ b/cloud_docs/02-concepts/01-deployments.md @@ -0,0 +1,154 @@ +--- +title: Deployments +description: Deploy your Serverpod app to Cloud, check deployment status, validate packages before deploying, and control what's included in the deployment. +--- + +# Deployments + +A deployment is your Serverpod app packaged, uploaded, built, and run on Cloud. Each `scloud deploy` produces a new immutable deployment with its own ID and lifecycle, and Cloud serves the most recent successful one. Subsequent deploys roll your app forward without anything else for you to do. + +## Deploy your app + +Before deploying, run `serverpod generate` so your models and endpoints are up to date. Then deploy with: + +```bash +scloud deploy +``` + +The CLI packages your project, uploads it, kicks off the build, and prints URLs you can access once the deployment is live: + +```text +✓ Project uploaded successfully! 🚀 + +When the server has started, you can access it at: + Web: https://my-app.serverpod.space/ + API: https://my-app.api.serverpod.space/ + Insights: https://my-app.insights.serverpod.space/ + +See `scloud domain --help` to set up a custom domain. +``` + +Each deployment moves through four stages: **Booster liftoff** (upload), **Orbit acceleration** (build), **Orbital insertion** (deploy), and **Pod commissioning** (service ready). + +:::tip + +If your app includes a Flutter web frontend, bump the version in your Flutter app's `pubspec.yaml` before each deploy. Otherwise an old version of the web app may be cached by the user's browser. + +::: + +Pass `-v` (`--verbose`) for detailed output, or `--dart-version` to override the Dart SDK used at build time. + +## Check deployment status + +Watch the latest deployment as it runs: + +```bash +scloud deployment show +``` + +Output: + +```text +Tracking status of my-app deploy 4583d0a1-3d0a-400e-a9a5-9880da6abc94, started at 2026-06-03 13:41:21: + +✓ Booster liftoff: Upload successful! +✓ Orbit acceleration: Build successful! +✓ Orbital insertion: Deploy successful! +✓ Pod commissioning: Service successful! 🚀 +``` + +List recent deployments: + +```bash +scloud deployment list +``` + +Inspect a specific deployment by its ID: + +```bash +scloud deployment show +``` + +Stream the build log for a deployment that failed during the build stage: + +```bash +scloud deployment build-log +``` + +## Validate before deploying + +A dry run packages your project and validates the package without uploading or building it: + +```bash +scloud deploy --dry-run +``` + +Preview the file tree that will be uploaded, with ignored files marked: + +```bash +scloud deploy --show-files +``` + +Combine the two flags to inspect what will be uploaded without deploying: + +```bash +scloud deploy --dry-run --show-files +``` + +Save the package to a local zip (useful for CI inspection or air-gapped environments): + +```bash +scloud deploy --output deployment.zip --dry-run +``` + +## Configure what's included + +A `.scloudignore` file in your project root controls which files are packaged. The syntax mirrors `.gitignore`. + +By default, every file ignored by `.gitignore` is also excluded from the deployment. To include files that `.gitignore` excludes, prefix the pattern with `!` in your `.scloudignore`: + +```text title=".scloudignore" +# Exclude a specific file +/specific_file.txt + +# Exclude all log files +*.log + +# Exclude a directory and its contents +/large_dir/ + +# Include generated code, even if ignored by .gitignore +!lib/src/generated/ +``` + +`scloud` may generate intermediate files under `.scloud/` directories. Add the pattern to your project's `.gitignore` so they don't end up in version control: + +```text title=".gitignore" +# scloud deployment generated files +**/.scloud/ +``` + +Verify your ignore patterns: + +```bash +scloud deploy --dry-run --show-files +``` + +## Troubleshooting + +**Build failure.** Stream the build log and look for lines beginning with `ERROR:` or `FAILED:`: + +```bash +scloud deployment build-log +``` + +Common causes are missing dependencies in `pubspec.yaml` or compile errors in your code. + +**Package resolution failure.** Update your `pubspec.yaml` (run `dart pub get` locally to verify), then redeploy. + +## Related + +- [Deployment hooks](/cloud/reference/deployment/deployment-hooks) for pre- and post-deploy automation. +- [Handling private dependencies](/cloud/reference/deployment/handling-private-dependencies) for private package access during the build. +- [Including non-Dart files](/cloud/reference/deployment/assets) for static assets. +- [Deploying using GitHub Actions](/cloud/reference/deployment/github-automation) for CI/CD setups. diff --git a/cloud_docs/02-concepts/_category_.json b/cloud_docs/02-concepts/_category_.json new file mode 100644 index 00000000..c325a82f --- /dev/null +++ b/cloud_docs/02-concepts/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Concepts", + "position": 2, + "collapsed": false, + "className": "sidebar-icon-getting-started" +} diff --git a/cloud_docs/02-guides/_category_.json b/cloud_docs/02-guides/_category_.json index 3092df44..ae4d94ef 100644 --- a/cloud_docs/02-guides/_category_.json +++ b/cloud_docs/02-guides/_category_.json @@ -1,5 +1,6 @@ { "label": "Guides", + "position": 3, "collapsed": false, "className": "sidebar-icon-learn" } diff --git a/cloud_docs/reference/01-deployment/01-deploying-your-application.md b/cloud_docs/reference/01-deployment/01-deploying-your-application.md deleted file mode 100644 index c9f915c8..00000000 --- a/cloud_docs/reference/01-deployment/01-deploying-your-application.md +++ /dev/null @@ -1,193 +0,0 @@ -# Deploying your application - -Serverpod Cloud makes it easy to deploy your Serverpod applications with a single command. You can also perform dry runs to validate your deployment package without actually deploying it. - -### Generating code before deployment - -Before deploying your application, you should always generate your code to ensure all your models and endpoints are up to date: - -```bash -serverpod generate -``` - -### Standard deployment - -To deploy your application to Serverpod Cloud: - -```bash -scloud deploy -``` - -The CLI will: - -1. Package your application -2. Upload it to Serverpod Cloud -3. Start the deployment process -4. Provide URLs to access your application when ready - -#### Successful deployment - -After a successful deployment, you'll see a message like: - -```text -Project uploaded successfully! 🚀 - -When the server has started, you can access it at: -Web: https://my-app.serverpod.space/ -API: https://my-app.api.serverpod.space/ -Insights: https://my-app.insights.serverpod.space/ - -See the `scloud domain` command to set up a custom domain. -``` - -### Performing a dry run - -A dry run lets you validate your deployment package without actually deploying it: - -```bash -scloud deploy --dry-run -``` - -This will: - -- Package your application -- Validate the package contents -- Skip the actual upload and deployment - -### Getting more deployment insights - -For detailed information during deployment: - -```bash -scloud deploy --verbose -``` - -This shows detailed error messages if something goes wrong. - -### Viewing the file tree - -To see a visual representation of the file tree that will be uploaded: - -```bash -scloud deploy --show-files -``` - -This displays a tree structure showing all files that will be included in the deployment, as well as files that are ignored (marked with "(ignored)"). - -### Controlling concurrency - -You can control how many files are zipped concurrently during packaging: - -```bash -scloud deploy --concurrency 5 -``` - -Higher concurrency can speed up deployments. - -### Checking deployment status - -Check the status of your most recent deployment: - -```bash -scloud deployment show -``` - -List all deployments: - -```bash -scloud deployment list -``` - -When listing all deployments, you'll see output similar to this: - -```text -# | Project | Deploy Id | Status | Started | Finished | Info ---+---------+--------------------------------------+---------+---------------------+---------------------+----------------------------------- -0 | my-app | 3bbb0189-784b-4b9b-a3d9-c84f4c787f54 | FAILURE | 2025-03-28 13:42:38 | 2025-03-28 13:43:33 | User build FAILURE - see build log -1 | my-app | 4a60a5ec-067c-4c76-8ecd-30a6410c1dc2 | SUCCESS | 2025-03-27 15:24:57 | 2025-03-27 15:27:50 | -2 | my-app | 73e66b41-64fc-4920-b6ef-4918cc6ceca1 | FAILURE | 2025-03-27 15:19:37 | 2025-03-27 15:20:34 | User build FAILURE - see build log -3 | my-app | 4bb1e636-3ec8-4f78-b294-32c80efd513a | SUCCESS | 2025-03-27 10:12:36 | 2025-03-27 10:19:48 | -``` - -View detailed logs for a specific deployment using its ID: - -```bash -scloud deployment show 73e66b41-64fc-4920-b6ef-4918cc6ceca1 -``` - -### Managing deployment files - -The `.scloudignore` file lets you control which files are included in your deployment package, using syntax similar to `.gitignore`: - -- By default, any files ignored by `.gitignore` are also excluded from your deployment -- To include files that are ignored by `.gitignore`, prefix the pattern with `!` in your `.scloudignore` file - -#### Adding to .gitignore - -Deployment may generate files which are placed in directories named `.scloud`. -These should not be committed to version control, which can be avoided by adding this to your root .gitignore: - -``` -# scloud deployment generated files -**/.scloud/ -``` - -#### Syntax and examples - -```text -# Comments start with a hash -/specific_file.txt # Exclude a specific file -*.log # Exclude all log files -/large_dir/ # Exclude a directory and its contents - -# Override .gitignore rules -!lib/src/generated/ # Include all generated code, even if ignored by .gitignore -``` - -Verify your ignore patterns are working as expected: - -```bash -scloud deploy --dry-run --show-files -``` - -This will show you the file tree without actually deploying, so you can verify which files are included or excluded. - -## 💡 Best Practices - -- **Use `.scloudignore`**: Exclude unnecessary files from your deployment package -- **Add `**/.scloud/` to .gitignore**: Exclude generated deployment files from your git repository -- **Use version control**: Commit your code before deploying to ensure you can rollback if needed -- **Check deployment status**: Use `scloud deployment show` to monitor your deployment -- **Use deployment hooks**: Automate build steps and post-deployment tasks with `pre_deploy` and `post_deploy` hooks (see [Deployment Hooks](./04-deployment-hooks.md)) - -## Troubleshooting - -If your deployment fails: - -- Check the deployment status: - - ```bash - scloud deployment show - ``` - -- View build logs for the latest deployment: - - ```bash - scloud deployment build-log - ``` - -### Common build failures - -| Error Type | Possible Causes | Solution | -|------------|-----------------|----------| -| Package resolution | Missing dependencies | Update your `pubspec.yaml` file | -| Build errors | Code compilation issues | Fix the code errors shown in logs | - -> **Tip:** Look for lines starting with "ERROR:" or "FAILED:" in the build logs for quick troubleshooting. - -## Related documentation - -- [Deployment Hooks](./04-deployment-hooks.md) - Automate build steps and post-deployment tasks -- [Handling Private Dependencies](./02-handling-private-dependencies.md) - Manage private package dependencies -- [Assets](./03-assets.md) - Include static assets in your deployment -- [GitHub Automation](./06-github-automation.md) - Automate Serverpod Cloud deployment using GitHub actions diff --git a/cloud_docs/reference/01-deployment/04-deployment-hooks.md b/cloud_docs/reference/01-deployment/04-deployment-hooks.md index a26fd57e..f149ab0f 100644 --- a/cloud_docs/reference/01-deployment/04-deployment-hooks.md +++ b/cloud_docs/reference/01-deployment/04-deployment-hooks.md @@ -191,5 +191,5 @@ project: ## Related documentation -- [Deploying Your Application](./01-deploying-your-application.md) - Learn about the deployment process +- [Deployments](/cloud/concepts/deployments) - Deploy operations, status checks, package validation, and `.scloudignore` configuration. - [Configuration Overview](/cloud/guides/passwords) - Overview of secrets, variables, and passwords diff --git a/cloud_docs/reference/01-deployment/05-dart-sdk-versions.md b/cloud_docs/reference/01-deployment/05-dart-sdk-versions.md index 4612e918..bd287347 100644 --- a/cloud_docs/reference/01-deployment/05-dart-sdk-versions.md +++ b/cloud_docs/reference/01-deployment/05-dart-sdk-versions.md @@ -169,5 +169,5 @@ environment: ## Related documentation -- [Deploying Your Application](./01-deploying-your-application.md) - Learn how to deploy your Serverpod application +- [Deployments](/cloud/concepts/deployments) - Deploy operations, status checks, package validation, and `.scloudignore` configuration. - [Handling Private Dependencies](./02-handling-private-dependencies.md) - Manage workspace dependencies diff --git a/cloud_docs/reference/_category_.json b/cloud_docs/reference/_category_.json index 373bfbff..b33299a7 100644 --- a/cloud_docs/reference/_category_.json +++ b/cloud_docs/reference/_category_.json @@ -1,6 +1,6 @@ { "label": "Reference", "collapsed": true, - "position": 3, + "position": 4, "className": "sidebar-icon-reference" } diff --git a/docusaurus.config.js b/docusaurus.config.js index 810ba0e7..056efc6e 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -217,6 +217,11 @@ const config = { from: ['/concepts/scheduling'], to: '/concepts/scheduling/setup', }, + { + // Cloud IA: Deploying your application content consolidated into the Deployments concept page. + from: ['/cloud/reference/deployment/deploying-your-application'], + to: '/cloud/concepts/deployments', + }, ], }, ], From e38471e4d7635abbd24f131a216ac5f1ff3dd1fa Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Thu, 4 Jun 2026 14:21:39 +0100 Subject: [PATCH 2/3] docs(cloud): Tighten Deployments concept flow and recover dropped flag info --- cloud_docs/02-concepts/01-deployments.md | 27 ++++++++++++++++-------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/cloud_docs/02-concepts/01-deployments.md b/cloud_docs/02-concepts/01-deployments.md index d162784a..7d2527e4 100644 --- a/cloud_docs/02-concepts/01-deployments.md +++ b/cloud_docs/02-concepts/01-deployments.md @@ -9,7 +9,7 @@ A deployment is your Serverpod app packaged, uploaded, built, and run on Cloud. ## Deploy your app -Before deploying, run `serverpod generate` so your models and endpoints are up to date. Then deploy with: +Deploy your project to Cloud: ```bash scloud deploy @@ -28,15 +28,13 @@ When the server has started, you can access it at: See `scloud domain --help` to set up a custom domain. ``` -Each deployment moves through four stages: **Booster liftoff** (upload), **Orbit acceleration** (build), **Orbital insertion** (deploy), and **Pod commissioning** (service ready). +Other flags: -:::tip +- `-v` (`--verbose`): detailed output. +- `--dart-version`: override the Dart SDK used at build time. +- `--concurrency=`: how many files are zipped in parallel during packaging (default `5`). -If your app includes a Flutter web frontend, bump the version in your Flutter app's `pubspec.yaml` before each deploy. Otherwise an old version of the web app may be cached by the user's browser. - -::: - -Pass `-v` (`--verbose`) for detailed output, or `--dart-version` to override the Dart SDK used at build time. +To regenerate code or run other tasks before each deploy, configure a pre-deploy hook (see [Deployment hooks](/cloud/reference/deployment/deployment-hooks)). ## Check deployment status @@ -46,7 +44,7 @@ Watch the latest deployment as it runs: scloud deployment show ``` -Output: +The command prints a real-time lifecycle update: ```text Tracking status of my-app deploy 4583d0a1-3d0a-400e-a9a5-9880da6abc94, started at 2026-06-03 13:41:21: @@ -57,12 +55,23 @@ Tracking status of my-app deploy 4583d0a1-3d0a-400e-a9a5-9880da6abc94, started a ✓ Pod commissioning: Service successful! 🚀 ``` +The output marks each of the four lifecycle stages: **Booster liftoff** (upload), **Orbit acceleration** (build), **Orbital insertion** (deploy), and **Pod commissioning** (service ready). + List recent deployments: ```bash scloud deployment list ``` +The list shows deploy IDs alongside status and timestamps: + +```text +# | Project | Deploy Id | Status | Started | Finished | Info +--+---------+--------------------------------------+---------+---------------------+---------------------+----------------------------------- +0 | my-app | 4583d0a1-3d0a-400e-a9a5-9880da6abc94 | SUCCESS | 2026-06-03 13:41:21 | 2026-06-03 13:46:08 | +1 | my-app | 73e66b41-64fc-4920-b6ef-4918cc6ceca1 | FAILURE | 2026-06-02 15:19:37 | 2026-06-02 15:20:34 | User build FAILURE - see build log +``` + Inspect a specific deployment by its ID: ```bash From 79d88ce3d4cffd6e64793775e4bf62a5deace86b Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Thu, 4 Jun 2026 14:39:44 +0100 Subject: [PATCH 3/3] docs(cloud): Trim the deployments redirect comment --- docusaurus.config.js | 1 - 1 file changed, 1 deletion(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 056efc6e..aafd4fad 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -218,7 +218,6 @@ const config = { to: '/concepts/scheduling/setup', }, { - // Cloud IA: Deploying your application content consolidated into the Deployments concept page. from: ['/cloud/reference/deployment/deploying-your-application'], to: '/cloud/concepts/deployments', },