Skip to main content

Get Started with DBOS

Deploy Your First App to the Cloud

1. Initialize your application

Create a folder for your app with a virtual environment, then enter the folder and activate the virtual environment.

You can choose another name for your app. Names should be 3 to 30 characters long and contain only lowercase letters and numbers, dashes, and underscores.

python3 -m venv my-app/.venv
cd my-app
source .venv/bin/activate

Then, install dbos.

pip install dbos

Next, initialize your folder with a sample application.

dbos init
What if dbos init fails?

If you see an error message ImportError: no pq wrapper available, try to install the binary package:

pip install "psycopg[binary]"

If the binary package is unavailable for your machine, try to install libpq:

brew install libpq

If this fails, please check out the psycopg3 installation guide.

2. 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

3. Deploy to DBOS Cloud!

pip freeze > requirements.txt

Then, run this command to deploy your app to DBOS Cloud. Follow the prompts to sign in and to provision a Postgres database server on the cloud.

dbos-cloud app deploy

In less than a minute, it should print Access your application at <URL>. To see that your app is working, visit <URL> in your browser.

https://<username>-my-app.cloud.dbos.dev

Welcome to DBOS!

Congratulations, you've successfully deployed your first app to DBOS Cloud! You can see your deployed app in the cloud console.

Run Your App Locally

1. Setup a Local Postgres Server

First, your app needs a local Postgres server to connect to.

Local database connection info is stored in the dbos-config.yaml file in your app folder. If you're using your own Postgres database, make sure you update this file with the correct connection info.

Instructions to start a local Postgres server

You can install Docker on macOS through Docker Desktop.

Then, run this script to launch Postgres in a Docker container:

export PGPASSWORD=dbos
# Docker may require sudo -E
python3 start_postgres_docker.py

If successful, the script should print Database started successfully!

2. Run the app

Next, run a schema migration to create tables for your app in your database. If successful, the migration should print Completed schema migration...

dbos migrate

Finally, start the app.

dbos start
http://localhost:8000/

Welcome to DBOS!

Congratulations, you've started a DBOS app locally! To learn more about building DBOS apps, check out our Python programming guide.