From 7e4516adcf3bd4210490a1415e5d1eb0bc1a9693 Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Wed, 10 Jun 2026 11:42:47 +0100 Subject: [PATCH 1/2] docs(cloud): Reframe PAT and deployment hooks as concepts, non-Dart files as a guide --- cloud_docs/02-concepts/01-deployments.md | 6 +- .../02-concepts/06-personal-access-tokens.md | 139 +++++++++++++ cloud_docs/02-concepts/07-deployment-hooks.md | 66 ++++++ .../02-guides/06-ship-non-dart-files.md | 128 ++++++++++++ .../reference/01-deployment/03-assets.md | 177 ---------------- .../01-deployment/04-deployment-hooks.md | 195 ------------------ .../reference/03-personal-access-tokens.md | 177 ---------------- .../reference/cli/commands/auth/_auth.md | 6 +- docusaurus.config.js | 12 ++ 9 files changed, 351 insertions(+), 555 deletions(-) create mode 100644 cloud_docs/02-concepts/06-personal-access-tokens.md create mode 100644 cloud_docs/02-concepts/07-deployment-hooks.md create mode 100644 cloud_docs/02-guides/06-ship-non-dart-files.md delete mode 100644 cloud_docs/reference/01-deployment/03-assets.md delete mode 100644 cloud_docs/reference/01-deployment/04-deployment-hooks.md delete mode 100644 cloud_docs/reference/03-personal-access-tokens.md diff --git a/cloud_docs/02-concepts/01-deployments.md b/cloud_docs/02-concepts/01-deployments.md index f1f2c67e..27d199ff 100644 --- a/cloud_docs/02-concepts/01-deployments.md +++ b/cloud_docs/02-concepts/01-deployments.md @@ -33,7 +33,7 @@ Other flags: - `--dart-version`: override the Dart SDK used at build time. - `--concurrency=`: how many files are zipped in parallel during packaging (default `5`). -To regenerate code or run other tasks before each deploy, configure a pre-deploy hook. See [Deployment hooks](/cloud/reference/deployment/deployment-hooks). +To regenerate code or run other tasks before each deploy, configure a pre-deploy hook. See [Deployment hooks](/cloud/concepts/deployment-hooks). ## Check deployment status @@ -157,7 +157,7 @@ Common causes are missing dependencies in `pubspec.yaml` or compile errors in yo ## Related -- [Deployment hooks](/cloud/reference/deployment/deployment-hooks) for pre- and post-deploy automation. +- [Deployment hooks](/cloud/concepts/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. +- [Ship non-Dart files with your server](/cloud/guides/ship-non-dart-files) for shipping static assets like configuration and templates. - [Automate deployment with GitHub Actions](/cloud/reference/deployment/github-automation) for CI/CD setups. diff --git a/cloud_docs/02-concepts/06-personal-access-tokens.md b/cloud_docs/02-concepts/06-personal-access-tokens.md new file mode 100644 index 00000000..b3928e0d --- /dev/null +++ b/cloud_docs/02-concepts/06-personal-access-tokens.md @@ -0,0 +1,139 @@ +--- +title: Personal access tokens +description: Create personal access tokens to authenticate scloud in CI pipelines, scripts, and headless environments without interactive login. +--- + +# Personal access tokens + +Personal access tokens let you authenticate the Serverpod Cloud CLI without interactive login. Use them in CI pipelines, scripts, or headless environments where you cannot run `scloud auth login`. + +## When to use tokens + +Use a personal access token when: + +- Running `scloud` in a CI/CD pipeline (GitHub Actions, GitLab CI, and so on). +- Automating deploys or other `scloud` commands from a script or cron job. +- Using `scloud` on a server or container with no browser for interactive login. + +For everyday development on your machine, `scloud auth login` is simpler; it stores credentials locally and you don't need to handle tokens. + +## Create a token + +Sign in first, then run: + +```bash +scloud auth create-token +``` + +Example output: + +```text +✅ Successfully created an API token. + +Use the --token option or the SERVERPOD_CLOUD_TOKEN environment variable to +authenticate with this token in scloud commands. + +The token is only visible once: +c2FzAZxXRnzFeN2xTo6xVInh3k3bNanACBRM7ux5AYOLQDgzK82PZvdRn0N_f2WqLPCZ +``` + +:::caution + +The CLI prints the token once. Store it somewhere secure (a secret in your CI system, a password manager). It can't be retrieved again. + +::: + +### Token expiration + +By default, tokens expire after 30 days of non-use. Adjust this when creating the token: + +```bash +# Expire after 7 days of non-use +scloud auth create-token --idle-ttl 7d + +# Never expire from non-use (still valid until revoked or until --expire-at) +scloud auth create-token --no-idle-ttl + +# Expire at a fixed ISO 8601 time +scloud auth create-token --expire-at 2026-12-31T23:59:59Z +``` + +Durations accept `s`, `m`, `h`, and `d` units. + +## List authentication sessions + +To see your active sessions and tokens with their IDs, creation, last-used, and expiry times: + +```bash +scloud auth list +``` + +Use the Token Id column to identify a token before revoking it. + +## Revoke a token + +Revoke a specific token by its ID from `scloud auth list`: + +```bash +scloud auth logout --token-id +``` + +Log out the current session instead: + +```bash +scloud auth logout +``` + +Revoke every session and token at once: + +```bash +scloud auth logout --all +``` + +A revoked token can no longer authenticate. + +## Use a token with scloud + +The CLI accepts a token two ways. For CI pipelines and shell sessions, prefer the `SERVERPOD_CLOUD_TOKEN` environment variable. The `--token` flag is a per-command override. + +### Environment variable + +Set the variable once so every subsequent `scloud` call in that shell uses the token: + +```bash +export SERVERPOD_CLOUD_TOKEN="your-token-here" +scloud deploy +scloud log +``` + +Best for CI pipelines and shell sessions where you set the secret once and run multiple commands. + +### Command-line flag + +Pass the token directly to any command: + +```bash +scloud --token="your-token-here" deploy +scloud --token="your-token-here" log +``` + +The flag applies only to that command. Useful when the token lives in a script variable or a short-lived secret. + +If both `--token` and `SERVERPOD_CLOUD_TOKEN` are set, `--token` takes precedence. + +## Use a token in GitHub Actions + +Store the token as a repository secret, then pass it to the official action: + +```yaml +- uses: serverpod/serverpod_cloud_deploy@v1 + with: + token: ${{ secrets.SERVERPOD_CLOUD_TOKEN }} +``` + +A full setup walkthrough lives in the [serverpod_cloud_deploy action README](https://github.com/serverpod/serverpod_cloud_deploy). + +## Related + +- [`scloud auth`](/cloud/reference/cli/commands/auth) for the full reference on `auth login`, `create-token`, `list`, and `logout`. +- [CLI environment variables](/cloud/reference/cli/env_vars) for all `scloud` environment variables. diff --git a/cloud_docs/02-concepts/07-deployment-hooks.md b/cloud_docs/02-concepts/07-deployment-hooks.md new file mode 100644 index 00000000..7e65f91c --- /dev/null +++ b/cloud_docs/02-concepts/07-deployment-hooks.md @@ -0,0 +1,66 @@ +--- +title: Deployment hooks +description: Run custom scripts at fixed points in a Serverpod Cloud deploy. Pre-deploy hooks handle setup like code generation; post-deploy hooks send notifications. +--- + +# Deployment hooks + +Deployment hooks let you run your own scripts at fixed points during a deploy. Use them to build a Flutter web client, regenerate Serverpod code, run database migrations, send a Slack notification on release, or any other custom step that has to happen before or after Cloud receives your project. Without hooks, those steps live in a separate command you remember to run yourself. + +## When to use hooks + +Hooks come in two shapes: + +- **`pre_deploy`** for anything that has to run *before* Cloud receives your project (regenerate Serverpod code, build a Flutter web client, compile non-Dart assets, run database migration scripts, run a test suite as a deploy gate). +- **`post_deploy`** for anything that should fire *after* the upload completes (Slack notification, kick a downstream pipeline, mark a release in your tracker). + +If your deploy doesn't depend on either, don't add hooks. Deploys work without them. + +## Configure hooks + +Hooks live in `scloud.yaml` under `project.scripts`. Each hook accepts either a single command (string) or a list of commands (array). + +Single command: + +```yaml +project: + projectId: my-project + scripts: + pre_deploy: serverpod generate + post_deploy: echo "Deployment complete" +``` + +Multiple commands run sequentially: + +```yaml +project: + projectId: my-project + scripts: + pre_deploy: + - serverpod generate + - serverpod run flutter_build + post_deploy: + - curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK -d '{"text":"Deployed"}' +``` + +## How scripts run + +Each command runs in your project directory (the one containing `scloud.yaml`) through the system shell (`bash -c` on macOS and Linux, `cmd /c` on Windows). Scripts inherit the environment variables of the shell that invoked `scloud deploy`, so CI-set secrets and your local `PATH` are available. Commands in an array run sequentially; output streams to your terminal in real time as each one executes. + +A non-zero exit code halts further commands in that hook. + +:::warning + +`pre_deploy` and `post_deploy` failures are not symmetric: + +- 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. + +Plan your scripts accordingly: put anything that must succeed before your code ships in `pre_deploy`. + +::: + +## Related + +- [Deployments](/cloud/concepts/deployments) for the deploy lifecycle around hooks. +- [`scloud deploy`](/cloud/reference/cli/commands/deploy) for the deploy command and its flags. diff --git a/cloud_docs/02-guides/06-ship-non-dart-files.md b/cloud_docs/02-guides/06-ship-non-dart-files.md new file mode 100644 index 00000000..b0134800 --- /dev/null +++ b/cloud_docs/02-guides/06-ship-non-dart-files.md @@ -0,0 +1,128 @@ +--- +title: Ship non-Dart files with your server +description: Include configuration files, templates, data, or other non-Dart assets alongside your Serverpod Cloud server and read them at runtime. +--- + +# Ship non-Dart files with your server + +Bundle non-Dart files (configuration, templates, CSV data, binary blobs) with your server code on Cloud. This guide walks through the convention for placing assets in your project and reading them from your server. + +## Before you start + +- A Serverpod server project on disk (alongside `lib/` and `bin/`). +- The `scloud` CLI installed and authenticated. See [Install scloud](/cloud/getting-started/installation). + +## Add files to your project + +Place files in an `assets/` folder at the root of your server project, alongside `lib/` and `bin/`: + +```text +my_server/ +├── assets/ +│ ├── config/ +│ │ └── settings.json +│ ├── templates/ +│ │ └── email_template.html +│ └── data/ +│ └── initial_data.csv +├── lib/ +├── bin/ +└── pubspec.yaml +``` + +Then deploy: + +```bash +scloud deploy +``` + +Cloud zips your project directory and includes every file that isn't excluded from the deploy package (see [Control what gets uploaded](#control-what-gets-uploaded) below). The folder name `assets/` is a convention; you can call it anything, but `assets/` is what other Serverpod projects use and what the rest of this guide assumes. + +To preview which files Cloud will upload before deploying: + +```bash +scloud deploy --dry-run --show-files +``` + +## Read an asset at runtime + +Use Dart's `dart:io` library and a path relative to the server's working directory: + +```dart +import 'dart:io'; + +Future readSettings() async { + final file = File('./assets/config/settings.json'); + return file.readAsString(); +} +``` + +The path is relative to the directory the server runs from, not to the source file. Use `./assets/` everywhere; absolute paths break across local and deployed environments. + +For binary data (images, PDFs, archives), use `readAsBytes()` instead of `readAsString()`. + +## Read common file types + +### Load JSON configuration + +Parse a JSON file into a `Map` on startup or per request: + +```dart +import 'dart:io'; +import 'dart:convert'; + +Future> loadConfig() async { + final file = File('./assets/config/app_config.json'); + final contents = await file.readAsString(); + return jsonDecode(contents) as Map; +} +``` + +### Render a template + +Read an HTML or text template, then interpolate values: + +```dart +import 'dart:io'; + +Future loadWelcomeEmail({required final String name}) async { + final template = await File('./assets/templates/welcome_email.html').readAsString(); + return template.replaceAll('{{name}}', name); +} +``` + +### Read CSV data + +For tabular data, read line by line: + +```dart +import 'dart:io'; + +Future> readCsv() async { + return File('./assets/data/initial_data.csv').readAsLines(); +} +``` + +For more complex parsing, the [`csv` package](https://pub.dev/packages/csv) handles quoting and escaping. + +## Control what gets uploaded + +Two files affect what's in the deployment: + +- **`.gitignore`.** Anything excluded here is also excluded from the deploy. +- **`.scloudignore`.** Cloud-specific exclusions. Same syntax as `.gitignore`. Use the `!` prefix to opt files back in that `.gitignore` excluded. + +Hidden files (those starting with `.`) are excluded by default. If you need them shipped, opt back in via `.scloudignore`. See [Deployments](/cloud/concepts/deployments) for the full picture of the deployment package. + +## Troubleshooting + +**File not found at runtime.** The path is relative to the server's working directory, not to the source file. Use `./assets/`. Verify the file is in the deployment with `scloud deploy --dry-run --show-files` before debugging at runtime. + +**Asset missing from the deployment.** Check `.gitignore` and `.scloudignore`. Patterns like `*.json` exclude every `.json` file unless you opt them back in with `!assets/**`. + +**Large assets slow deploys.** Asset files add to your deployment package size. Large folders slow uploads and the Cloud build step. For files larger than a few megabytes that don't need to live in version control, consider an external object store and reading them from the network instead. + +## Related + +- [Deployments](/cloud/concepts/deployments) for what's in the deployment package and how `.scloudignore` works. +- [`scloud deploy`](/cloud/reference/cli/commands/deploy) for the deploy command and its flags. diff --git a/cloud_docs/reference/01-deployment/03-assets.md b/cloud_docs/reference/01-deployment/03-assets.md deleted file mode 100644 index 0a479448..00000000 --- a/cloud_docs/reference/01-deployment/03-assets.md +++ /dev/null @@ -1,177 +0,0 @@ -# Including non-Dart files with your server - -Serverpod Cloud allows you to include non-Dart files (assets) with your server deployment. These files are copied to your deployed server and can be accessed from your server code at runtime. - -## How it works - -Serverpod Cloud automatically copies all files located in an `assets` folder in the root of your server project during deployment. These files are then available in your deployed server using relative paths from the server's working directory. - -## Setting up assets - -1. Create an `assets` folder in the root of your server project (alongside `lib/`, `bin/`, etc.) - -2. Add your files to the `assets` folder: - -```bash -my_server/ -├── assets/ -│ ├── config/ -│ │ └── settings.json -│ ├── templates/ -│ │ └── email_template.html -│ └── data/ -│ └── initial_data.csv -├── lib/ -├── bin/ -└── pubspec.yaml -``` - -3. Deploy your application as usual: - -```bash -scloud deploy -``` - -All files in the `assets` folder will be automatically included in your deployment. - -## Accessing assets in your server code - -Files in the `assets` folder can be referenced from your server code using the relative path `./assets/path/to/file.txt`. - -### Reading asset files - -Use Dart's `dart:io` library to read asset files: - -```dart -import 'dart:io'; - -Future readConfigFile() async { - final file = File('./assets/config/settings.json'); - final contents = await file.readAsString(); - return contents; -} -``` - -### Checking if files exist - -Before reading a file, you may want to check if it exists: - -```dart -import 'dart:io'; - -Future readAssetFile(String path) async { - final file = File('./assets/$path'); - - if (await file.exists()) { - return await file.readAsString(); - } - - return null; -} -``` - -## Common use cases - -### Configuration files - -Store configuration files that your server needs at runtime: - -```dart -import 'dart:io'; -import 'dart:convert'; - -Future> loadConfig() async { - final file = File('./assets/config/app_config.json'); - final contents = await file.readAsString(); - return jsonDecode(contents) as Map; -} -``` - -### Template files - -Include HTML or text templates for email notifications or reports: - -```dart -import 'dart:io'; - -Future loadEmailTemplate() async { - final file = File('./assets/templates/welcome_email.html'); - return await file.readAsString(); -} -``` - -### Static data files - -Include CSV files, JSON data, or other static data files: - -```dart -import 'dart:io'; - -Future> readCsvData() async { - final file = File('./assets/data/initial_data.csv'); - final lines = await file.readAsLines(); - return lines; -} -``` - -### Binary files - -Read binary files like images or PDFs: - -```dart -import 'dart:io'; - -Future> loadImageBytes() async { - final file = File('./assets/images/logo.png'); - return await file.readAsBytes(); -} -``` - -## Complete example - -Here's a complete example of using assets in a Serverpod endpoint: - -```dart -import 'dart:io'; -import 'dart:convert'; -import 'package:serverpod/serverpod.dart'; - -class ConfigEndpoint extends Endpoint { - Future> getConfig(Session session) async { - try { - final file = File('./assets/config/app_config.json'); - - if (!await file.exists()) { - throw Exception('Config file not found'); - } - - final contents = await file.readAsString(); - final config = jsonDecode(contents) as Map; - - return config; - } catch (e) { - throw Exception('Failed to load config: $e'); - } - } -} -``` - -## Important notes - -1. **Folder Location**: The `assets` folder must be in the root of your server project, not in `lib/` or any subdirectory. - -2. **File Paths**: Always use the `./assets/` prefix when referencing files. Paths are relative to the server's working directory. - -3. **Deployment**: Assets are included automatically during deployment. No additional configuration is needed. - -4. **File Size**: Consider the size of your assets, as they are included in the deployment package. Large files may increase deployment time, or hit the size limit of the deployment package. - - -## Troubleshooting - -| Issue | Possible Solution | -|-------|------------------| -| File not found error | Verify the `assets` folder exists in the server project root and the file path is correct | -| Permission denied | Check file permissions in the assets folder | -| Assets not included in deployment | Ensure the `assets` folder is in the root directory and not excluded by `.scloudignore` | - diff --git a/cloud_docs/reference/01-deployment/04-deployment-hooks.md b/cloud_docs/reference/01-deployment/04-deployment-hooks.md deleted file mode 100644 index 2f8d7c42..00000000 --- a/cloud_docs/reference/01-deployment/04-deployment-hooks.md +++ /dev/null @@ -1,195 +0,0 @@ -# Deployment hooks - -Deployment hooks allow you to run custom scripts at specific points during the deployment lifecycle. This enables you to automate tasks such as building Flutter apps, running database migrations, or performing custom setup steps before or after deployment. - -## Overview - -Serverpod Cloud supports two types of deployment hooks: - -- **`pre_deploy`**: Scripts that run before your project is packaged and uploaded -- **`post_deploy`**: Scripts that run after your project has been successfully uploaded - -These hooks are configured in your `scloud.yaml` file and are executed in your project directory. - -## When hooks are executed - -### Pre-deploy hook - -The `pre_deploy` hook runs: - -1. After dependency validation -2. Before the project is zipped -3. Before the project is uploaded to Serverpod Cloud - -This is the ideal place for: - -- Building Flutter applications -- Running code generation -- Compiling assets -- Running tests -- Any preparation steps that need to happen before packaging - -### Post-deploy hook - -The `post_deploy` hook runs: - -1. After the project has been successfully uploaded -2. After the upload confirmation is received -3. Before the deployment process completes - -This is the ideal place for: - -- Sending deployment notifications -- Triggering external services -- Running post-deployment validation -- Any cleanup or follow-up tasks - -:::warning - -If a `pre_deploy` script fails, the deployment will be aborted before uploading. If a `post_deploy` script fails, the deployment will have already been uploaded, but the command will exit with an error. - -::: - -## Configuration format - -Deployment hooks are configured in your `scloud.yaml` file under the `project.scripts` section. You can specify scripts in two formats: - -### Single script (string) - -For a single command, use a string: - -```yaml -project: - projectId: my-project - scripts: - pre_deploy: serverpod run flutter_build - post_deploy: echo "Deployment complete" -``` - -### Multiple scripts (array) - -For multiple commands, use an array: - -```yaml -project: - projectId: my-project - scripts: - pre_deploy: - - serverpod generate - - serverpod run flutter_build - post_deploy: - - echo "Deployment uploaded successfully" - - curl -X POST https://api.example.com/webhook -``` - -## Examples - -### Building Flutter apps - -A common use case is building Flutter applications before deployment: - -```yaml -project: - projectId: my-project - scripts: - pre_deploy: serverpod run flutter_build -``` - -This ensures your Flutter web app is built and ready before the deployment package is created. - -### Code generation and building - -Generate code and build your Flutter app: - -```yaml -project: - projectId: my-project - scripts: - pre_deploy: - - serverpod generate - - serverpod run flutter_build -``` - -### Post-deployment notifications - -Send a notification after successful deployment: - -```yaml -project: - projectId: my-project - scripts: - post_deploy: | - curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL \ - -H 'Content-Type: application/json' \ - -d '{"text":"Deployment successful!"}' -``` - -### Complex pre-deploy workflow - -Run multiple preparation steps: - -```yaml -project: - projectId: my-project - scripts: - pre_deploy: - - echo "Starting deployment preparation..." - - serverpod generate - - serverpod run flutter_build - - echo "Preparation complete" -``` - -## Important considerations - -### Script execution environment - -- Scripts are executed in your project directory (the directory containing `scloud.yaml`). -- Scripts run using the system shell. -- Each script in an array is executed sequentially. -- Scripts have access to the same environment as your terminal. - -### Error handling - -- If any `pre_deploy` script fails (exits with non-zero status), the deployment is aborted. -- If any `post_deploy` script fails, the deployment has already been uploaded, but the command will exit with an error. -- Script output (stdout and stderr) is displayed in the terminal during execution. - -### Script dependencies - -- Ensure all commands and tools used in your hooks are available in your environment. -- Scripts should be idempotent when possible (safe to run multiple times). -- Consider using absolute paths for commands if there might be PATH issues. - -### Best practices - -1. **Keep scripts simple**: Complex logic should be in your application code or separate build scripts. -2. **Test locally**: Run your hook commands manually before adding them to `scloud.yaml`. -3. **Use arrays for multiple steps**: This makes it easier to see what's happening and debug issues. -4. **Document your hooks**: Add comments in your `scloud.yaml` or project README explaining why hooks are needed. -5. **Handle failures gracefully**: Consider what happens if a script fails and plan accordingly. - -## Troubleshooting - -### Script not running - -- Verify the script syntax in `scloud.yaml` is correct (YAML format). -- Check that the script path is correct if using file paths. -- Ensure the command is available in your PATH. - -### Script fails during deployment - -- Run the script manually in your project directory to test it. -- Check the error output in the terminal. -- Verify all dependencies and tools are installed. -- Consider adding error handling or validation to your scripts. - -### Script output not visible - -- Script output is displayed in real-time during deployment. -- Use `scloud deploy --verbose` for more detailed output -- Check that your script is actually producing output (some commands may be silent). - -## Related documentation - -- [Deployments](/cloud/concepts/deployments) - Deploy your app, check deployment status, and validate before deploying. -- [Passwords, secrets, and environment variables](/cloud/concepts/passwords-secrets-env-vars) - Project configuration tiers and operations. diff --git a/cloud_docs/reference/03-personal-access-tokens.md b/cloud_docs/reference/03-personal-access-tokens.md deleted file mode 100644 index 11d8418b..00000000 --- a/cloud_docs/reference/03-personal-access-tokens.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: Personal access tokens -sidebar_position: 8 ---- - -# Personal access tokens - -Personal access tokens let you authenticate the Serverpod Cloud CLI without -interactive login. Use them in CI pipelines, scripts, or headless environments -where you cannot run `scloud auth login`. - -## When to use tokens - -Use a personal access token when: - -- Running `scloud` in a CI/CD pipeline (e.g. GitHub Actions, GitLab CI). -- Automating deploys or other CLI commands from a script or cron job. -- Using the CLI on a server or container that has no browser for interactive login. - -For normal development on your machine, `scloud auth login` is usually simpler -because it stores credentials locally and you do not need to copy tokens. - -## Create a token - -You must be logged in to create a token. Run: - -```sh -scloud auth create-token -``` - -Example output: -```sh -✅ Successfully created an API token. - -Use the --token option or the SERVERPOD_CLOUD_TOKEN environment variable to -authenticate with this token in scloud commands. - -The token is only visible once: -c2FzAZxXRnzFeN2xTo6xVInh3k3bNanACBRM7ux5AYOLQDgzK82PZvdRn0N_f2WqLPCZ -``` - -The CLI prints the new token once. Store it somewhere secure (e.g. a secret in -your CI system). The token is not shown again. - -### Token expiration - -By default, created tokens have a time-to-live (TTL) and expire after -30 days of non-use. You can change this when creating the token: - -```sh -# Expire after 7 days of non-use -scloud auth create-token --idle-ttl 7d - -# No expiration from non-use (token still valid until you revoke it or set --expire-at) -scloud auth create-token --no-idle-ttl - -# Expire at a fixed time (ISO 8601) -scloud auth create-token --expire-at 2026-12-31T23:59:59Z -``` - -Durations support units such as `s`, `m`, `h`, and `d`. - -## List authentication sessions - -To see your current sessions and personal access tokens (including their IDs and -creation/expiry info): - -```sh -scloud auth list -``` - -Use this to find a token ID before revoking it with `scloud auth logout --token-id`. - -## Log out and revoke tokens - -- **Log out the current session** (e.g. after `auth login` on your machine): - - ```sh - scloud auth logout - ``` - -- **Revoke a specific personal access token** (use the ID from `scloud auth list`): - - ```sh - scloud auth logout --token-id - ``` - -- **Revoke all sessions and tokens** (including all personal access tokens): - - ```sh - scloud auth logout --all - ``` - -After you revoke a token, it can no longer be used for authentication. - -## Using a token with the CLI - -You can pass the token in two ways: the `--token` option or the -`SERVERPOD_CLOUD_TOKEN` environment variable. - -### Option: `--token` - -Use the global `--token` option with any `scloud` command: - -```sh -scloud --token="your-token-here" deploy -scloud --token="your-token-here" log -``` - -The token applies only to that command. This is useful when you have the token -in a script variable or a secret and do not want to put it in the environment. - -### Environment variable: `SERVERPOD_CLOUD_TOKEN` - -Set the environment variable so every `scloud` command in that process uses the token: - -```sh -export SERVERPOD_CLOUD_TOKEN="your-token-here" -scloud deploy -scloud log -``` - -This is convenient in CI and scripts where you set the secret once (e.g. in the -pipeline config) and then run multiple commands. - -If both `--token` and `SERVERPOD_CLOUD_TOKEN` are set, the `--token` option -takes precedence. - -## Example: CI pipeline - -In a CI pipeline, store the token as a secret and expose it as e.g. -`SERVERPOD_CLOUD_TOKEN`. - -### GitHub CI - -If using GitHub, the action -[serverpod-cloud-deploy](https://github.com/marketplace/actions/serverpod-cloud-deploy) -can be used to automate deployment to Serverpod Cloud such as in this GitHub -workflow example. - -```yml -name: Automated Serverpod Cloud deploy - -on: - push: - branches: [main] - -permissions: - contents: read - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Setup Flutter SDK - uses: subosito/flutter-action@v2 - - - name: Activate serverpod command - run: dart pub global activate serverpod_cli - - - uses: serverpod/serverpod-cloud-deploy@v1 - with: - token: ${{ secrets.MY_SERVERPOD_CLOUD_ACCESS_TOKEN }} -``` - -## Result - -- You can run `scloud` in CI and scripts without interactive login. -- Tokens can be scoped with expiration and idle TTL. -- You can list and revoke tokens with `scloud auth list` and `scloud auth logout`. - -## Related documentation - -- [Auth command reference](/cloud/reference/cli/commands/auth) — Full option reference for `scloud auth login`, `create-token`, `list`, and `logout`. -- [CLI environment variables](/cloud/reference/cli/env_vars) — All `scloud` environment variables, including `SERVERPOD_CLOUD_TOKEN`. diff --git a/cloud_docs/reference/cli/commands/auth/_auth.md b/cloud_docs/reference/cli/commands/auth/_auth.md index aa8d60ce..92f0b59b 100644 --- a/cloud_docs/reference/cli/commands/auth/_auth.md +++ b/cloud_docs/reference/cli/commands/auth/_auth.md @@ -2,9 +2,9 @@ Handle user authentication. -See also the [personal access tokens (PAT) guide](/cloud/reference/personal-access-tokens) -on how to prepare and use personal access tokens for CI pipelines, scripts, or -headless environments where you cannot run `scloud auth login`. +See also the [Personal access tokens](/cloud/concepts/personal-access-tokens) +concept page on how to prepare and use personal access tokens for CI pipelines, +scripts, or headless environments where you cannot run `scloud auth login`. ## `auth login` diff --git a/docusaurus.config.js b/docusaurus.config.js index 8fda3739..032e146d 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -237,6 +237,18 @@ const config = { from: ['/cloud/guides/database'], to: '/cloud/concepts/database', }, + { + from: ['/cloud/reference/personal-access-tokens'], + to: '/cloud/concepts/personal-access-tokens', + }, + { + from: ['/cloud/reference/deployment/assets'], + to: '/cloud/guides/ship-non-dart-files', + }, + { + from: ['/cloud/reference/deployment/deployment-hooks'], + to: '/cloud/concepts/deployment-hooks', + }, ], }, ], From f43d0643611a2447b41c96e410bed827d94c0d8d Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Wed, 10 Jun 2026 13:18:35 +0100 Subject: [PATCH 2/2] docs(cloud): Address review on concepts reframe --- cloud_docs/01-getting-started/02-launch.md | 2 +- .../02-concepts/06-personal-access-tokens.md | 4 ++-- cloud_docs/02-guides/06-ship-non-dart-files.md | 14 +++++++++----- 3 files changed, 12 insertions(+), 8 deletions(-) diff --git a/cloud_docs/01-getting-started/02-launch.md b/cloud_docs/01-getting-started/02-launch.md index 027c890a..5b77d2dd 100644 --- a/cloud_docs/01-getting-started/02-launch.md +++ b/cloud_docs/01-getting-started/02-launch.md @@ -28,7 +28,7 @@ It creates a Cloud project and ships its first version. The CLI walks you throug - **Project ID.** scloud suggests a default from your pubspec name (for example, `my-app`). Press Enter to accept, or type a different ID. The project ID becomes part of your default URL (`.serverpod.space`). - **Plan.** Type `starter` or `growth` (see [Cloud plans](https://serverpod.dev/cloud) for details). Pick `starter` for a first deploy. Starter includes a 1-month free trial; no credit card required. - **Database.** Press Enter for yes if you want Cloud to provision and manage a Postgres database for your server. Type `n` if your app doesn't need a database, or if you plan to connect to your own. -- **Pre-deploy hooks.** Hooks run scripts before each deploy. scloud may offer to add `serverpod generate` and a Flutter build hook (if your project defines one). Accept the ones that match your project. See [Deployment hooks](/cloud/reference/deployment/deployment-hooks) for details. +- **Pre-deploy hooks.** Hooks run scripts before each deploy. scloud may offer to add `serverpod generate` and a Flutter build hook (if your project defines one). Accept the ones that match your project. See [Deployment hooks](/cloud/concepts/deployment-hooks) for details. After the final confirmation, scloud creates the Cloud project, writes a `scloud.yaml` linking subsequent commands to it, uploads your code, and starts the deploy. diff --git a/cloud_docs/02-concepts/06-personal-access-tokens.md b/cloud_docs/02-concepts/06-personal-access-tokens.md index b3928e0d..477ee791 100644 --- a/cloud_docs/02-concepts/06-personal-access-tokens.md +++ b/cloud_docs/02-concepts/06-personal-access-tokens.md @@ -1,5 +1,5 @@ --- -title: Personal access tokens +sidebar_label: Personal access tokens description: Create personal access tokens to authenticate scloud in CI pipelines, scripts, and headless environments without interactive login. --- @@ -37,7 +37,7 @@ The token is only visible once: c2FzAZxXRnzFeN2xTo6xVInh3k3bNanACBRM7ux5AYOLQDgzK82PZvdRn0N_f2WqLPCZ ``` -:::caution +:::warning The CLI prints the token once. Store it somewhere secure (a secret in your CI system, a password manager). It can't be retrieved again. diff --git a/cloud_docs/02-guides/06-ship-non-dart-files.md b/cloud_docs/02-guides/06-ship-non-dart-files.md index b0134800..981eaf58 100644 --- a/cloud_docs/02-guides/06-ship-non-dart-files.md +++ b/cloud_docs/02-guides/06-ship-non-dart-files.md @@ -1,11 +1,11 @@ --- -title: Ship non-Dart files with your server +sidebar_label: Ship non-Dart files with your server description: Include configuration files, templates, data, or other non-Dart assets alongside your Serverpod Cloud server and read them at runtime. --- # Ship non-Dart files with your server -Bundle non-Dart files (configuration, templates, CSV data, binary blobs) with your server code on Cloud. This guide walks through the convention for placing assets in your project and reading them from your server. +Bundle non-Dart files (configuration, templates, CSV data, binary blobs) with your server code on Cloud. Place them in an `assets/` folder at the project root and read them with `./assets/` at runtime. ## Before you start @@ -36,7 +36,7 @@ Then deploy: scloud deploy ``` -Cloud zips your project directory and includes every file that isn't excluded from the deploy package (see [Control what gets uploaded](#control-what-gets-uploaded) below). The folder name `assets/` is a convention; you can call it anything, but `assets/` is what other Serverpod projects use and what the rest of this guide assumes. +Cloud zips your project directory and includes every file that isn't excluded from the deploy package (see [Control what gets uploaded](#control-what-gets-uploaded) below). `assets/` is the Serverpod naming convention for this folder. You can call it anything, but the rest of this guide assumes `assets/`. To preview which files Cloud will upload before deploying: @@ -114,14 +114,18 @@ Two files affect what's in the deployment: Hidden files (those starting with `.`) are excluded by default. If you need them shipped, opt back in via `.scloudignore`. See [Deployments](/cloud/concepts/deployments) for the full picture of the deployment package. +:::tip + +Asset files count toward your deployment package size. Large folders slow uploads and the Cloud build step. For files larger than a few megabytes that don't need to live in version control, consider an external object store and reading them from the network instead. + +::: + ## Troubleshooting **File not found at runtime.** The path is relative to the server's working directory, not to the source file. Use `./assets/`. Verify the file is in the deployment with `scloud deploy --dry-run --show-files` before debugging at runtime. **Asset missing from the deployment.** Check `.gitignore` and `.scloudignore`. Patterns like `*.json` exclude every `.json` file unless you opt them back in with `!assets/**`. -**Large assets slow deploys.** Asset files add to your deployment package size. Large folders slow uploads and the Cloud build step. For files larger than a few megabytes that don't need to live in version control, consider an external object store and reading them from the network instead. - ## Related - [Deployments](/cloud/concepts/deployments) for what's in the deployment package and how `.scloudignore` works.