add recommendations for CI/CD (#181)

Some recommendations to setup a CI/CD pipeline for a DBOS cloud
application. Document
dbos-inc/dbos-transact-ts#653 and
dbos-inc/dbos-transact-py#136

---------

Signed-off-by: Peter Kraft <petereliaskraft@gmail.com>
Co-authored-by: Peter Kraft <petereliaskraft@gmail.com>

docs/cloud-tutorials/application-management.md

@@ -20,7 +20,7 @@ Your application is deployed using the name in its `dbos-config.yaml`.
 Application names should be between 3 and 30 characters and must contain only lowercase letters and numbers, dashes (`-`), and underscores (`_`). Application names are unique within an [organization](account-management#organization-management).
 
 The first time you deploy an application, you are prompted to choose to which [database instance](../cloud-tutorials/database-management.md) to connect your app, or to provision one if you have none.
-Multiple applications can connect to the same database instance (server) but must use separate databases within that server (the `app_db_name` field in `dbos-config.yaml`).
+Multiple applications can connect to the same database instance (server)—they are deployed to isolated databases on that server.
 
 Each time you deploy an application, the following steps execute:
 
@@ -43,7 +43,7 @@ If you edit your application, run `dbos-cloud app deploy` again to apply the lat
 * During your first deploy, you can programatically specify a particular database instance through the `-d <database-instance-name>`.
 * During the first deploy, you can enable time travel for your application with `--enable-timetravel`. You can delete and re-deploy an existing application to enable time travel.
 * You don't have to worry about changing database server connection parameters like `hostname` or `password` in `dbos-config.yaml` to deploy an application to the cloud&#8212;DBOS automatically applies the connection information of your cloud database instance.
-* You cannot change the application database (`app_db_name`) of a deployed application. You must delete and re-deploy the application.
+* You cannot change the database of a deployed application. You must delete and re-deploy the application.
 :::
 
 

docs/cloud-tutorials/cicd.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 11
+title: CI/CD Best Practices
+---
+
+## Staging and Production Environments
+
+To make it easy to test changes to your application without affecting your production users, we recommend using separate staging and production environments.
+You can do this by deploying your application with different names for staging and production.
+For example, when deploying `my-app` to staging, deploy using:
+
+```shell
+dbos-cloud app deploy my-app-staging
+```
+
+When deploying to production, use:
+
+```shell
+dbos-cloud app deploy my-app-prod
+```
+
+`my-app-staging` and `my-app-prod` are completely separate and isolated DBOS applications.
+There's nothing special about the `-staging` and `-prod` suffixes—you can use any names you like.
+
+:::info
+If you manually specify the application database name by setting `app_db_name` in `dbos_config.yaml`, you must ensure each environment uses a different value of `app_db_name`.
+:::
+
+## Secrets management
+To make secrets, such as API keys, available to your application running in DBOS Cloud, we recommend using environment variables.
+
+First, declare the environment variable in the `env` section of `dbos-config.yaml`:
+
+```yaml
+env:
+    API_KEY: ${API_KEY}
+```
+
+Then the value of `API_KEY` in your client environment will be submitted with your application and supplied to it as an environment variable on DBOS Cloud.
+Only environment variables declared in `dbos-config.yaml` are submitted and supplied like this.
+
+## Authentication
+You should use [refresh tokens](account-management#authenticating-programatically) to programmatically authenticate your CI/CD user with DBOS Cloud.
+
+:::info
+Upgrading to a DBOS Cloud paid plan will unlock [multi-user organizations](account-management#organization-management) which you can use to setup dedicated users for CI/CD.
+:::

docs/cloud-tutorials/database-management.md

@@ -24,7 +24,7 @@ dbos-cloud db provision <database-instance-name> -U <database-username>
 
 :::info
 A Postgres database instance (server) can host many independent databases used by different applications.
-You can configure to which database on this server your app connects through the `app_db_name` field in its `dbos-config.yaml`.
+Each application is deployed to an isolated database by default; you can configure this through the `app_db_name` field in `dbos-config.yaml`.
 :::
 
 :::info

docs/python/reference/configuration.md

@@ -39,7 +39,7 @@ Every field is required unless otherwise specified.
 - **port**: Database server port. For local deployment only, not used in DBOS Cloud.
 - **username**: Username with which to connect to the database server. For local deployment only, not used in DBOS Cloud.
 - **password**: Password with which to connect to the database server.  We recommend using an environment variable for this field, instead of plain text. For local deployment only, not used in DBOS Cloud.
-- **app_db_name**: Name of the application database. Defaults to the app name, with dashes replaced by underscores.
+- **app_db_name**: (optional): Name of the application database. If not supplied, the application name (with dashes replaced with underscores for compatibility) is used instead.
 - **sys_db_name** (optional): Name of the system database in which DBOS stores internal state. Defaults to `{app_db_name}_dbos_sys`.  For local deployment only, not used in DBOS Cloud.
 - **ssl_ca** (optional): If using SSL/TLS to securely connect to a database, path to an SSL root certificate file.  Equivalent to the [`sslrootcert`](https://www.postgresql.org/docs/current/libpq-ssl.html) connection parameter in `psql`.
 - **local_suffix** (optional): Whether to suffix `app_db_name` with '_local'. Set to true when doing local development using a DBOS Cloud database. For local development only, not used in DBOS Cloud.
@@ -54,7 +54,6 @@ database:
   port: 5432
   username: 'postgres'
   password: ${PGPASSWORD}
-  app_db_name: 'hello_python'
   migrate:
     - alembic upgrade head
 ```

docs/typescript/reference/configuration.md

@@ -40,7 +40,7 @@ Every field is required unless otherwise specified.
 - **port**: Database server port. For local deployment only, not used in DBOS Cloud.
 - **username**: Username with which to connect to the database server. For local deployment only, not used in DBOS Cloud.
 - **password**: Password with which to connect to the database server.  We recommend using an environment variable for this field, instead of plain text. For local deployment only, not used in DBOS Cloud.
-- **app_db_name**: Name of the application database. Defaults to the app name, with dashes replaced by underscores.
+- **app_db_name**: (optional): Name of the application database. If not supplied, the application name (with dashes replaced with underscores for compatibility) is used instead.
 - **sys_db_name** (optional): Name of the system database in which DBOS stores internal state. Defaults to `{app_db_name}_dbos_sys`.  For local deployment only, not used in DBOS Cloud.
 - **app_db_client** (optional): Client to use for connecting to the application database. Must be one of `knex`, `drizzle`, `typeorm`, or `prisma`.  Defaults to `knex`.  The client specified here is the one used in [`TransactionContext`](../reference/contexts#transactioncontextt).
 - **ssl_ca** (optional): If using SSL/TLS to securely connect to a database, path to an SSL root certificate file.  Equivalent to the [`sslrootcert`](https://www.postgresql.org/docs/current/libpq-ssl.html) connection parameter in `psql`.
@@ -57,7 +57,6 @@ database:
   port: 5432
   username: 'postgres'
   password: ${PGPASSWORD}
-  app_db_name: 'hello'
   app_db_client: 'knex'
   migrate: ['npx knex migrate:latest']
   rollback: ['npx knex migrate:rollback']

docs/typescript/tutorials/using-drizzle.md

@@ -97,7 +97,6 @@ database:
   port: 5432
   username: postgres
   password: ${PGPASSWORD}
-  app_db_name: dbos_hello_app
   connectionTimeoutMillis: 3000
   app_db_client: drizzle
   migrate:

docs/typescript/tutorials/using-knex.md

@@ -104,7 +104,6 @@ database:
   port: 5432
   username: postgres
   password: ${PGPASSWORD}
-  app_db_name: hello
   app_db_client: knex
   migrate:
     - npx knex migrate:latest

docs/typescript/tutorials/using-prisma.md

@@ -106,7 +106,6 @@ database:
   hostname: 'localhost'
   port: 5432
   username: 'postgres'
-  app_db_name: 'hello_prisma'
   password: ${PGPASSWORD}
   connectionTimeoutMillis: 3000
   app_db_client: prisma

docs/typescript/tutorials/using-typeorm.md

@@ -126,7 +126,6 @@ database:
   hostname: 'localhost'
   port: 5432
   username: 'postgres'
-  app_db_name: 'hello_typeorm'
   password: ${PGPASSWORD}
   connectionTimeoutMillis: 3000
   app_db_client: typeorm