Skip to main content

Adding DBOS To Your App

This guide shows you how to add the open source DBOS Transact library to your existing application to durably execute it and make it resilient to any failure. It also shows you how to serverlessly deploy your application to DBOS Cloud and scale it to millions of users.

Using DBOS Transact​

1. Install DBOS​

pip install DBOS into your application, then create a DBOS configuration file.

pip install dbos
dbos init --config

2. Add the DBOS Initializer​

In your program's main function, add these two lines of code. These initialize DBOS when your program starts.

DBOS()
DBOS.launch()

3. Connect Your Application to Postgres​

DBOS is backed by Postgres, so you need to connect your app to a Postgres database. You can use a DBOS Cloud database, a Docker container, or a local Postgres installation.

After you've connected to Postgres, try launching your application. It should run normally, but log Initializing DBOS and DBOS launched on startup. Congratulations! You've integrated DBOS into your application.

Instructions to set up Postgres

You can connect your local application to a Postgres database hosted in DBOS Cloud.

First, set a password for your DBOS Cloud database:

dbos-cloud db reset-password

Then connect your local app to your cloud database. When prompted, enter the password you just set.

dbos-cloud db local

Alternatively, if you already have a Postgres database, update dbos-config.yaml with its connection information.

4. Start Building With DBOS​

At this point, you can add any DBOS decorator or method to your application. For example, you can annotate one of your functions as a workflow and the functions it calls as steps. DBOS durably executes the workflow so if it is ever interrupted, upon restart it automatically recovers to the last completed step.

You can add DBOS to your application incrementally—it won't interfere with code that's already there. It's totally okay for your application to have one DBOS workflow alongside thousands of lines of non-DBOS code.

To learn more about programming with DBOS, check out the guide.

@DBOS.step()
def step_one():
    ...

@DBOS.step()
def step_two():
    ...

@DBOS.workflow()
def workflow()
    step_one()
    step_two()

Deploying to DBOS Cloud​

Any application you build with DBOS can be serverlessly deployed to DBOS Cloud. DBOS Cloud can seamlessly autoscale your application to millions of users and provides built-in dashboards for observability and monitoring.

1. Install the DBOS Cloud CLI​

The Cloud CLI requires Node.js 20 or later.

Instructions to install Node.js

Run the following commands in your terminal:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm

nvm install 22
nvm use 22

Run this command to install it.

npm i -g @dbos-inc/dbos-cloud@latest

2. Create a requirements.txt File​

Create a requirements.txt file listing your application's dependencies.

pip freeze > requirements.txt

3. Define a Start Command​

Set the start command in the runtimeConfig section of your dbos-config.yaml to your application's launch command.

If your application includes an HTTP server, configure it to listen on port 8000.

To test that it works, try launching your application with dbos start.

runtimeConfig:
  start:
    - "fastapi run"

4. Deploy to DBOS Cloud​

Run this single command to deploy your application to DBOS Cloud!

dbos-cloud app deploy