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 don't have to worry about setting database server connection parameters like hostname or password to deploy an application to the cloud—DBOS automatically applies the connection information of your cloud database server.
• You cannot change the database of a deployed application. You must delete and re-deploy the application.

Dependency Management

Python

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.

TypeScript

For TypeScript applications, DBOS Cloud installs all dependencies from your package-lock.json file (or from package.json if no lockfile is provided). The maximum size of your application after all dependencies are installed is 2 GB.

After all dependencies are installed, your application is compiled using npm run build.

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:

• The cloud console provides a web UI for viewing your applications and their traces and logs.

• To retrieve the last N seconds of your application's logs, run dbos-cloud app logs -l <N>. Note that new log entries take a few seconds to appear.

• To retrieve the status of a particular application, run dbos-cloud app status <app-name>. To list all applications, run dbos-cloud app list.

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.