Skip to main content

Application Management

Deploying Applications​

To deploy your application to DBOS Cloud or update an existing application, run this command in its root directory:

dbos-cloud app deploy

Each time you deploy an application, the following steps execute:

  1. Upload: An archive of your application folder is created and uploaded to DBOS Cloud. This archive can be up to 500 MB in size.
  2. Configuration: Your application's dependencies are installed.
  3. Migration: If you specify database migrations in your dbos-config.yaml, these are run on your cloud database.
  4. Deployment: Your application is deployed to a number of Firecracker microVMs. By default, these have 1 vCPU and 512MB of RAM. The amount of memory allocated to each microVM is configurable.

After an application is deployed, it is assigned a domain of the form https://<username>-<app-name>.cloud.dbos.dev/. If your account is part of an organization, organization name is used instead of username.

tip
  • Applications should serve requests from port 8000 (Python—the default port for FastAPI and Gunicorn) or 3000 (TypeScript—the default port for Express and Koa).
  • Multiple applications can connect to the same Postgres database server—they are deployed to isolated databases on that server.
  • You cannot change the database of a deployed application. You must delete and re-deploy the application.

Applications Configuration​

You need to provide a valid dbos-config.yaml file when deploying an application to DBOS Cloud. The required fields are:

  • name: Your application name. This is the name with which your application is registered.
  • language: node or python
  • runtimeConfig.start: the command used to start your application. For example, fastapi run

Note that some fields from dbos-config.yaml will be ignored during cloud deployments:

  • database_url and database connection-related fields. DBOS Cloud automatically applies the connection information of your cloud database server.
  • runtimeConfig.admin_port: DBOS Cloud communicates with Transact admin port on port 3001.

Dependency Management​

For Python applications, DBOS Cloud installs all dependencies from your requirements.txt file. The maximum size of your application after all dependencies are installed is 2 GB.

Customizing MicroVM Setup​

DBOS Pro subscribers can provide a setup script that runs before their application is configured. This script can customize the runtime environment for your application, for example installing system packages and libraries.

A setup script must be specified in your dbos-config.yaml like so:

dbos-config.yaml
runtimeConfig:
    # Script DBOS Cloud runs to customize your application runtime.
    # Requires a DBOS Pro subscription.
    setup:
        - "./build.sh"
    # Command DBOS Cloud executes to start your application.
    start: <your-start-command>

A setup script may install system packages or libraries or otherwise customize the microVM image. For example:

build.sh
#!/bin/bash

# Install the traceroute package for use in your application
apt install traceroute

Ignoring files with .dbosignore​

A .dbosignore file at the root of your project instructs the DBOS Cloud CLI to exclude resources from application deployment. The syntax for this file is similar to .gitignore:

  • Patterns are compatible with the fast-glob library
  • Lines ending with / are transformed into a recursive ignore /** to exclude everything within a directory.
  • Lines starting with # are ignored.
  • Some patterns are automatically excluded:
**/.dbos/**
**/node_modules/**
**/dist/**
**/.git/**
**/dbos-config.yaml
**/venv/**
**/.venv/**
**/.python-version

Monitoring and Debugging Applications​

Here are some useful tools to monitor and debug applications:

Managing Application Versions​

Each time you deploy an application, it creates a new version with a unique ID. You can view all previous versions of your application from the cloud console or list them by running:

dbos-cloud app versions <app-name>

You can redeploy a previous version of your application by passing --previous-version <version-id> to the app deploy command.

dbos-cloud app deploy --previous-version <version-id>

This will fail if the previous and current versions use different database schemas.

Updating Applications​

To update your application metadata, run:

dbos-cloud app update <app-name>

See the DBOS Cloud CLI reference for a list of properties you can update. Note that updating an application metadata does not trigger a redeploy of the code, which you can do with the app deploy command.

Deleting Applications​

To delete an application, run:

dbos-cloud app delete <app-name>

You can also drop the application database with the --dropdb argument. As each application has its own isolated database, this does not affect your other applications.

dbos-cloud app delete <app-name> --dropdb
warning

This is a destructive operation and cannot be undone.