Merge remote-tracking branch 'origin/main' into simpler-quickstart-pr…

…ogramming-tutorial

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

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 <string>`: 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 <string>`: Your DBOS Cloud username.
+It provides a URL to a secure login portal you can use to authenticate from your browser.
 
 ---
 

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."
+  }
+}

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 <database-name>
+```
+
+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/<username>/<app-name>
+```
+
+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&#8212;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 <N>`](../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
+```

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 <database-name> -a <admin-username> -W <admin-password>
+```
+
+:::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&#8212;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-name>
+```
+
+### 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 <database-name>
+```
+
+Take care&#8212;this irreversibly delete all data on the instance.

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

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/).

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 <project-name>
+cd <project-name>
+```
+
+### Registration
+
+Let's start by creating a DBOS Cloud account.
+From your DBOS application directory, run the following command:
+
+```
+npx dbos-cloud register -u <username>
+```
+
+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 `<username> 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 <database-name> -a <admin-username> -W <admin-password>
+```
+
+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 <database-name>
+```
+
+If successful, the command should print `Successfully registered <app-name>!`
+
+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 <app-name>! Access your application at <URL>`
+The URL should look like `https://cloud.dbos.dev/apps/<username>/<app-name>`
+Your application is now live at that URL!
+
+To see that your app is working, visit `<URL>/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!

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 <project-name>
+npx -y @dbos-inc/dbos-sdk init -n <project-name>
 ```
 
 This creates a folder for your project, configures its layout, and installs required dependencies.

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

docs/tutorials/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "Tutorials",
+  "label": "DBOS SDK Tutorials",
   "position": 2,
   "link": {
     "type": "generated-index",