diff --git a/docs/api-reference/_category_.json b/docs/api-reference/_category_.json index 64117791..b6d2ab5b 100644 --- a/docs/api-reference/_category_.json +++ b/docs/api-reference/_category_.json @@ -1,6 +1,6 @@ { "label": "Reference", - "position": 3, + "position": 4, "link": { "type": "generated-index", "description": "A complete reference for the DBOS SDK." diff --git a/docs/api-reference/cloud-cli.md b/docs/api-reference/cloud-cli.md index 47219d7d..7ad481ad 100644 --- a/docs/api-reference/cloud-cli.md +++ b/docs/api-reference/cloud-cli.md @@ -12,7 +12,7 @@ The DBOS Cloud CLI helps you serverlessly run your applications on DBOS Cloud **Description:** This command creates and registers a new DBOS Cloud account. -It provides a URL to a secure login portal from which you can create an account from your browser. +It provides a URL to a secure login portal you can use to create an account from your browser. **Parameters:** - `-u, --username `: Your DBOS Cloud username. @@ -23,10 +23,7 @@ It provides a URL to a secure login portal from which you can create an account **Description:** This command logs you in to your DBOS Cloud account. -It provides a URL to a secure login portal from which you can log in to your account from your browser. - -**Parameters:** -- `-u, --username `: Your DBOS Cloud username. +It provides a URL to a secure login portal you can use to authenticate from your browser. --- diff --git a/docs/cloud-tutorials/_category_.json b/docs/cloud-tutorials/_category_.json new file mode 100644 index 00000000..5ff89317 --- /dev/null +++ b/docs/cloud-tutorials/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "DBOS Cloud Tutorials", + "position": 3, + "link": { + "type": "generated-index", + "description": "These tutorials help you learn how to build powerful DBOS applications." + } +} diff --git a/docs/cloud-tutorials/application-management.md b/docs/cloud-tutorials/application-management.md new file mode 100644 index 00000000..db2dadb3 --- /dev/null +++ b/docs/cloud-tutorials/application-management.md @@ -0,0 +1,72 @@ +--- +sidebar_position: 2 +title: Cloud Application Management +description: Learn how to manage DBOS Cloud applications +--- + +In this guide, you'll learn how to manage applications in DBOS Cloud. + +### Preliminaries + +Before following any of the steps in this guide, make sure you've created and registered a DBOS Cloud account. +Then, in your application root directory, log in to DBOS Cloud by running: + +``` +npx dbos-cloud login +``` + +To deploy an application, you need a database to connect to. +You can use the database you created in the [cloud quickstart](../getting-started/quickstart-cloud.md) or [provision](./database-management.md#provisioning-database-instances) a new one. +Additionally, you must define [schema migrations](./database-management.md#database-schema-management) to create your application's tables. + +### Registering and Deploying Applications + +The first step in deploying an application to DBOS Cloud is registering it. +To register an application, run the following command in your application root directory, where `database-name` is the name of a Postgres database instance you've [provisioned](./database-management.md#provisioning-database-instances): + +``` +npx dbos-cloud application register -d +``` + +Your application is automatically registered under the name in its `package.json`. + +After you've registered your application, deploy it to run it in the cloud. +Run this command in your application root directory: + +``` +npx dbos-cloud application deploy +``` + +When you deploy an application, DBOS Cloud first runs [`npx dbos-sdk migrate`](../api-reference/cli.md#npx-dbos-sdk-migrate) against your cloud database to apply all schema migrations you've defined. +It then starts your application. +After your application is deployed, DBOS Cloud hosts it at this URL, which is also printed by the deploy command: + +``` +https://cloud.dbos.dev/apps// +``` + +If you edit your application or schema, run `npx dbos-cloud application deploy` again to apply the latest migration and re-deploy the latest version. + +:::tip +You don't have to edit your `dbos-config.yaml` to deploy an application to the cloud—DBOS automatically takes care of that for you, applying the connection information of your cloud database. +::: + +### Monitoring and Debugging Applications + +DBOS provides many tools to monitor and debug applications: + +- To get a high-level view of all your applications and their traces and logs, check out [our dashboard](#). + +- To replay any past trace locally and figure out exactly what happened, check out our [time travel debugger](#). + +- To retrieve the last `N` seconds of your application's logs, run in your application root directory [`npx dbos-cloud application logs -l `](../api-reference/cloud-cli.md#npx-dbos-cloud-application-logs). Note that new log entries take a few seconds to appear. + +- To retrieve the status of a particular application, run in its root directory [`npx dbos-cloud application status`](../api-reference/cloud-cli.md#npx-dbos-cloud-application-status). To retrieve the statuses of all applications, run [`npx dbos-cloud application list`](../api-reference/cloud-cli.md#npx-dbos-cloud-application-list). + +### Deleting Applications + +If you want to delete an application, run in its root directory: + +``` +npx dbos-cloud application delete +``` diff --git a/docs/cloud-tutorials/database-management.md b/docs/cloud-tutorials/database-management.md new file mode 100644 index 00000000..01157425 --- /dev/null +++ b/docs/cloud-tutorials/database-management.md @@ -0,0 +1,80 @@ +--- +sidebar_position: 1 +title: Cloud Database Management +description: Learn how to manage DBOS Cloud database instances +--- + +In this guide, you'll learn how to manage database instances in DBOS Cloud. + +### Preliminaries + +Before following any of the steps in this guide, make sure you've created and registered a DBOS Cloud account. +Then, in your application root directory, log in to DBOS Cloud by running: + +``` +npx dbos-cloud login +``` + +### Provisioning Database Instances + +Before you can deploy an application to DBOS Cloud, you must provision a Postgres database instance for it. +You should choose a database name and an administrator username and password for your database instance. +Both the database instance name and the administrator username must contain only lowercase letters and numbers, dashes (`-`), and underscores (`_`). +To provision a database instance, run (this takes ~5-7 minutes): + +``` +npx dbos-cloud database provision -a -W +``` + +:::tip +Each Postgres database instance is a physical server that can host multiple independent Postgres databases for different applications. +You can define which Postgres database your application connects to through the `app_db_name` field in its [`dbos-config.yaml`](../api-reference/configuration.md#database). + +However, don't worry about setting the other database connection parameters like `hostname` or `password` for cloud deployment—DBOS automatically takes care of that for you, applying the connection information of your cloud database when you deploy an application. +::: + +:::tip +Remember your database administrator password! You need it to connect to our [time travel debugger](#). +::: + +To see a list of all provisioned instances, run: + +``` +npx dbos-cloud database list +``` + +To retrieve the status of a particular instance, run: + +``` +npx dbos-cloud database status +``` + +### Database Schema Management + +To manage your applications' database schemas, you must define schema migrations. +DBOS Cloud is compatible with any schema management tool as long as all its dependencies and assets are stored in your application directory. +We recommend using a Typescript-based migration tool like [Knex](https://knexjs.org/guide/migrations.html) or [TypeORM](https://typeorm.io/migrations). + +You configure your schema migrations in the `migrate` field of your [`dbos-config.yaml`](../api-reference/configuration.md). +You must supply a list of commands to run to migrate to your most recent schema version. +For example, if you are using [Knex](https://knexjs.org/guide/migrations.html), you might use: + +```yaml +database: + # Other fields omitted + migrate: ['npx knex migrate:latest'] +``` + +To run your migrations locally, run `npx dbos-sdk migrate`. + +When you [deploy](./application-management.md#registering-and-deploying-applications) an application to DBOS Cloud, it runs `npx dbos-sdk migrate` to apply all schema changes before starting your application. + +### Destroying Database Instances + +To destroy a database instance, run: + +``` +npx dbos-cloud database destroy +``` + +Take care—this irreversibly delete all data on the instance. \ No newline at end of file diff --git a/docs/explanations/_category_.json b/docs/explanations/_category_.json index 65a009dd..c1c3ff20 100644 --- a/docs/explanations/_category_.json +++ b/docs/explanations/_category_.json @@ -1,6 +1,6 @@ { "label": "Concepts and Explanations", - "position": 4, + "position": 5, "link": { "type": "generated-index", "description": "These explanations help you learn core DBOS concepts." diff --git a/docs/explanations/application-structure-explanation.md b/docs/explanations/application-structure-explanation.md index 303992f6..04b21151 100644 --- a/docs/explanations/application-structure-explanation.md +++ b/docs/explanations/application-structure-explanation.md @@ -110,4 +110,4 @@ Once you've written your functions, there are two basic ways to call them: 1. Any function (not just handlers) can be called from HTTP if it's annotated with the [`GetApi`](../api-reference/decorators#getapi) or [`PostApi`](../api-reference/decorators#postapi) decorators. See our [HTTP serving tutorial](../tutorials/http-serving-tutorial) for details. 2. Handlers and workflows can invoke other functions via their contexts' `invoke` ([workflow](../api-reference/contexts#workflowctxtinvoketargetclass), [handler](../api-reference/contexts#handlerctxtinvoketargetclass-workflowuuid)) method. -To learn more about each individual type of function and what it can do, see our [tutorials](../category/tutorials/). +To learn more about each individual type of function and what it can do, see our [tutorials](../category/dbos-sdk-tutorials/). diff --git a/docs/getting-started/quickstart-cloud.md b/docs/getting-started/quickstart-cloud.md new file mode 100644 index 00000000..ecf98776 --- /dev/null +++ b/docs/getting-started/quickstart-cloud.md @@ -0,0 +1,73 @@ +--- +sidebar_position: 5 +--- + +# DBOS Cloud Quickstart + +Here's how to deploy a DBOS application to the cloud in a few minutes! + +### Preliminaries + +We assume you've already completed the [quickstart](./quickstart.md). +Before starting this tutorial, instantiate a new DBOS application and `cd` into it by running the following commands: + +```bash +npx -y @dbos-inc/dbos-sdk init -n +cd +``` + +### Registration + +Let's start by creating a DBOS Cloud account. +From your DBOS application directory, run the following command: + +``` +npx dbos-cloud register -u +``` + +When you run the command, it will ask you for some information, then redirect you to a secure login portal. +Open the login portal in your browser and click `Confirm`, then create a new account. +After you're done, go back to the terminal. +If everything's working, the command should succeed and print ` successfully registered!`. + + +### Provisioning a Database Instance + +Next, let's provision a Postgres database instance your applications can connect to! +You should choose a database name and an administrator username and password for your database instance. +Both the database instance name and the administrator username must contain only lowercase letters and numbers, dashes (`-`), and underscores (`_`). +Run this command (it should take ~5 minutes to provision): + +``` +npx dbos-cloud database provision -a -W +``` + +If successful, the command should print `Database successfully provisioned!`. + +### Registering and Deploying an Application + +Now, we're ready to register and deploy your application to DBOS Cloud! +First, register your application by running this command, using your database instance name from the last step: + +``` +npx dbos-cloud application register -d +``` + +If successful, the command should print `Successfully registered !` + +Now, deploy your application to run it in the cloud! + +``` +npx dbos-cloud application deploy +``` + +This command will build your application, then deploy it to our serverless cloud platform. +If successful, it will print `Successfully deployed ! Access your application at ` +The URL should look like `https://cloud.dbos.dev/apps//` +Your application is now live at that URL! + +To see that your app is working, visit `/greeting/dbos` in your browser. +For example, if your username is `mike` and your app name is `hello`, visit `https://cloud.dbos.dev/apps/mike/hello/greeting/dbos`. +Just like in the [quickstart](./quickstart.md), you should get this message: `Hello, dbos! You have been greeted 1 times.` Each time you refresh the page, the counter should go up by one! + +Congratulations, you've sucessfully deployed your first application to DBOS Cloud! \ No newline at end of file diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 1a5dee7d..31d40d87 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -77,7 +77,7 @@ docker run hello-world To initialize a new DBOS application, run the following command, choosing a project name with no spaces or special characters: ```bash -npx @dbos-inc/dbos-sdk init -n +npx -y @dbos-inc/dbos-sdk init -n ``` This creates a folder for your project, configures its layout, and installs required dependencies. diff --git a/docs/index.md b/docs/index.md index b01ee343..80494955 100644 --- a/docs/index.md +++ b/docs/index.md @@ -39,7 +39,7 @@ Here are some of DBOS's core features: ### How to Use These Docs - If you're encountering DBOS for the first time, try our [quickstart](./getting-started/quickstart) and get an application up and running in less than five minutes. -- If you want to learn how to use DBOS's powerful features, check out our [tutorials](./category/tutorials). +- If you want to learn how to use DBOS's powerful features, check out our [tutorials](./category/dbos-sdk-tutorials). - If you want a detailed reference for the DBOS API, check out our [API reference](./category/reference). - If you want to learn how things work under the hood, check out our [explanation guides](./category/concepts-and-explanations). - If you want to see more complex applications built with DBOS, check out [our demo apps](./tutorials/demo-apps). diff --git a/docs/tutorials/_category_.json b/docs/tutorials/_category_.json index 0a028355..9b9ee8b3 100644 --- a/docs/tutorials/_category_.json +++ b/docs/tutorials/_category_.json @@ -1,5 +1,5 @@ { - "label": "Tutorials", + "label": "DBOS SDK Tutorials", "position": 2, "link": { "type": "generated-index",