Skip to main content

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:

serverpod generate

Standard Deployment

To deploy your application to Serverpod Cloud:

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:

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:

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:

scloud deploy --verbose

This shows files being included/excluded and detailed error messages if something goes wrong.

Controlling Concurrency

You can control how many files are zipped concurrently during packaging:

scloud deploy --concurrency 5

Higher concurrency can speed up deployments.

Checking Deployment Status

Check the status of your most recent deployment:

scloud status deploy

List all deployments:

scloud status deploy --list

When listing all deployments, you'll see output similar to this:

# | 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:

scloud status deploy --deploy 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

# 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:

scloud deploy --dry-run --verbose

💡 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 status deploy to monitor your deployment

Troubleshooting

If your deployment fails:

  • Check the deployment status:

    scloud status deploy
  • View build logs for the latest deployment:

    scloud status deploy --build-log

Common Build Failures

Error TypePossible CausesSolution
Package resolutionMissing dependenciesUpdate your pubspec.yaml file
Build errorsCode compilation issuesFix the code errors shown in logs

Tip: Look for lines starting with "ERROR:" or "FAILED:" in the build logs for quick troubleshooting.