Get Started with DBOS
Deploy Your First App to the Cloud
- Python
- TypeScript
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.
- macOS or Linux
- Windows (PowerShell)
- Windows (cmd)
python3 -m venv my-app/.venv
cd my-app
source .venv/bin/activate
python3 -m venv my-app/.venv
cd my-app
.venv\Scripts\activate.ps1
python3 -m venv my-app/.venv
cd my-app
.venv\Scripts\activate.bat
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
:
- macOS
- Linux
- Windows
brew install libpq
sudo apt install libpq5
Use the interactive windows installer to install Command Line Tools.
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
- macOS or Linux
- Windows
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
Download Node.js 20 or later from the official Node.js download page and install it.
After installing Node.js, create the following folder: C:\Users\%user%\AppData\Roaming\npm
(%user%
is the Windows user on which you are logged in).
Run this command to install it.
npm i -g @dbos-inc/dbos-cloud@latest
3. Deploy to DBOS Cloud!
First, run pip freeze
to create a
requirements file specifying your app's dependencies.
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.
Welcome to DBOS!
Congratulations, you've successfully deployed your first app to DBOS Cloud! You can see your deployed app in the cloud console.
1. Initialize your application
DBOS TypeScript requires Node.js 20 or later.
Instructions to install Node.js
- macOS or Linux
- Windows
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
Download Node.js 20 or later from the official Node.js download page and install it.
After installing Node.js, create the following folder: C:\Users\%user%\AppData\Roaming\npm
(%user%
is the Windows user on which you are logged in).
Initialize your app with this command.
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.
npx -y @dbos-inc/create@latest -n my-app
It creates and initializes a new folder named my-app/
with a sample app. Enter the folder to perform the next step.
cd my-app/
2. Deploy to DBOS Cloud!
Install the DBOS Cloud CLI.
npm i -g @dbos-inc/dbos-cloud@latest
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.
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
- Python
- TypeScript
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
- Launch Postgres with Docker
- Install Postgres
- macOS
- Linux
- Windows (PowerShell)
- Windows (cmd)
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
Follow the Docker Engine installation page to install Docker on several popular Linux distributions.
Then, run this script to launch Postgres in a Docker container:
export PGPASSWORD=dbos
# Docker may require sudo -E
python3 start_postgres_docker.py
You can install Docker on Windows through Docker Desktop.
Then, run this script to launch Postgres in a Docker container:
$env:PGPASSWORD = "dbos"
python3 start_postgres_docker.py
You can install Docker on Windows through Docker Desktop.
Then, run this script to launch Postgres in a Docker container:
set PGPASSWORD=dbos
python3 start_postgres_docker.py
If successful, the script should print Database started successfully!
- macOS
- Linux
- Windows (PowerShell)
- Windows (cmd)
Follow this guide to install Postgres on macOS.
Then, set the PGPASSWORD
environment variable to your Postgres password:
export PGPASSWORD=<your-postgres-password>
Follow these guides to install Postgres on popular Linux distributions.
Then, set the PGPASSWORD
environment variable to your Postgres password:
export PGPASSWORD=<your-postgres-password>
Follow this guide to install Postgres on Windows.
Then, set the PGPASSWORD
environment variable to your Postgres password:
$env:PGPASSWORD = "<your-postgres-password>"
Follow this guide to install Postgres on Windows.
Then, set the PGPASSWORD
environment variable to your Postgres password:
set PGPASSWORD=<your-postgres-password>
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
To see that it's working, visit this URL in your browser: 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.
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
- Launch Postgres with Docker
- Install Postgres
- macOS
- Linux
- Windows (PowerShell)
- Windows (cmd)
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
node start_postgres_docker.js
Follow the Docker Engine installation page to install Docker on several popular Linux distributions.
Then, run this script to launch Postgres in a Docker container:
export PGPASSWORD=dbos
# Docker may require sudo -E
node start_postgres_docker.js
You can install Docker on Windows through Docker Desktop.
Then, run this script to launch Postgres in a Docker container:
$env:PGPASSWORD = "dbos"
node start_postgres_docker.js
You can install Docker on Windows through Docker Desktop.
Then, run this script to launch Postgres in a Docker container:
set PGPASSWORD=dbos
node start_postgres_docker.js
If successful, the script should print Database started successfully!
- macOS
- Linux
- Windows (PowerShell)
- Windows (cmd)
Follow this guide to install Postgres on macOS.
Then, set the PGPASSWORD
environment variable to your Postgres password:
export PGPASSWORD=<your-postgres-password>
Follow these guides to install Postgres on popular Linux distributions.
Then, set the PGPASSWORD
environment variable to your Postgres password:
export PGPASSWORD=<your-postgres-password>
Follow this guide to install Postgres on Windows.
Then, set the PGPASSWORD
environment variable to your Postgres password:
$env:PGPASSWORD = "<your-postgres-password>"
Follow this guide to install Postgres on Windows.
Then, set the PGPASSWORD
environment variable to your Postgres password:
set PGPASSWORD=<your-postgres-password>
2. Run the app
Next, run a schema migration to create tables for your app in your database.
If successful, the migration should print Migration successful!
npx dbos migrate
Finally, build and start the app.
npm run build
npx dbos start
To see that it's working, visit this URL in your browser: http://localhost:3000/
Welcome to DBOS!
Congratulations, you've started a DBOS app locally! To learn more about building DBOS apps, check out our TypeScript programming guide.