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.