Merge pull request #119 from DefangLabs/jordan/launch-prep

Document BYOC

Author: jordanstephens

docs/concepts/_category_.json

@@ -1,9 +1,8 @@
 {
   "label": "Concepts",
-  "position": 300,
+  "position": 500,
   "link": {
     "type": "generated-index",
     "description": "Some concepts to help explain how the Defang system is organized and tooling that will help you manage your applications."
   }
 }
-

docs/concepts/debug.md

@@ -6,10 +6,10 @@ sidebar_position: 650
 
 # Debug
 
-Defang includes an AI-driven tool to help you debug your cloud applications. The AI assistant will use your service logs as well as the files in your project to help you identify and resolve issues.
+Defang includes an AI-driven tool to help you debug your cloud applications. The AI agent will use your service logs as well as the files in your project to help you identify and resolve issues.
 
 :::warning
-The AI debugging assistant is currently in preview and is currently limited in its capabilities. We plan to expand the capabilities of the AI assistant in the future.
+The AI debugging agent is currently in preview and is currently limited in its capabilities. We plan to expand the capabilities of the AI agent in the future.
 :::
 
 ## How it works

docs/concepts/deployment-modes.md

@@ -0,0 +1,25 @@
+---
+title: Defang Deployment Modes
+description: Defang provides three deployment modes which allow you to balance cost and resiliency.
+sidebar_position: 501
+---
+
+# Defang Deployment Modes
+
+Defang provides three deployment modes: development, staging, and production. These modes allow you to balance cost and resiliency according to your needs.
+
+* **Development**: This mode is used for development and testing purposes. It typically involves less stringent resource allocations and may include debugging tools and verbose logging to aid in development.
+* **Staging**: This mode serves as a pre-production environment where applications are tested in conditions that closely mimic production. It helps in identifying issues that might not be apparent in the development environment.
+* **Production**: This mode is used for live deployments. It involves optimized configurations for performance, security, and reliability. Resource allocations are typically higher, and debugging tools are minimized to ensure stability.
+
+## Deployment Mode Comparison
+
+| Feature | Development | Staging | Production |
+|-|-|-|-|
+| Build Resources | Builds will be run with 2x vCPUs | Builds will be run with 2x vCPUs | Builds will be run with 4x vCPUs |
+| Databases | Defang will provision resources optimized for burstable memory | | Defang will provision resources optimized for production |
+| Static Resources | | | Defang will provision a CDN |
+| Deployment | Previous deployments will be spun down before new deployments are spun up. | | Rolling updates will be used to deploy new versions. Defang will gradually replace services while maintaining at least the original number of replicas. |
+| Logging | Logs retained for 1 day to save costs. | | Logs retained for 30 days for compliance. |
+| Networking | | | Defang will provision a NAT gateway. |
+| DNS | Defang will provision shorter TTLs | | Defang will provision longer TTLs |

docs/concepts/generate.md

@@ -6,17 +6,17 @@ sidebar_position: 100
 
 # Generate
 
-Defang includes an AI-driven assistant that translates natural language prompts to an outline for your project that you can then refine. The AI assistant is available through the [Defang CLI](../getting-started/installing.md).
+Defang includes an AI-driven agent that translates natural language prompts to an outline for your project that you can then refine. The AI agent is available through the [Defang CLI](../getting-started/installing.md).
 
 :::info
-The AI assistant is currently in preview and only supports a limited set of prompts, varying in complexity. We plan to expand the capabilities of the AI assistant in the future.
+The AI agent is currently in preview and only supports a limited set of prompts, varying in complexity. We plan to expand the capabilities of the AI agent in the future.
 :::
 
-We are working on expanding the range of supported prompts and improving the accuracy of the AI assistant. If you have any feedback or suggestions, please let us know by [opening an issue](https://github.com/DefangLabs/defang/issues/new).
+We are working on expanding the range of supported prompts and improving the accuracy of the AI agent. If you have any feedback or suggestions, please let us know by [opening an issue](https://github.com/DefangLabs/defang/issues/new).
 
 ## Example Prompts
 
-Here are some example prompts that the AI assistant can help you with:
+Here are some example prompts that the AI agent can help you with:
 
 ```
 A basic service with 2 REST endpoints. The default endpoint will be for health check and should return a JSON object like this: { "status": "OK" }. The /echo endpoint will echo back all request parameters in the response.

docs/concepts/managed-storage/managed-postgres.md

@@ -38,6 +38,9 @@ You can also set the following optional environment variables to configure the m
 You can connect to the managed Postgres instance using the name of your service as the hostname, `POSTGRES_USER`, `POSTGRES_DB`, and `POSTGRES_PASSWORD` environment variables.
 
 ### Example
+:::info 
+For a smoother experience with Defang, we recommend using Postgres 14 for your container images. This version provides easier access and improved usability.
+:::
 
 ```yaml
   app:
@@ -55,7 +58,7 @@ You can connect to the managed Postgres instance using the name of your service
       # reference config variables by using ${<config name>}
       CONNECTURL: postgresql://postgres:${POSTGRES_PASSWORD}@database:5432/postgres?sslmode=require
   database:
-    image: postgres:15
+    image: postgres:14
     x-defang-postgres: true
     ports:
       - mode: host
@@ -69,6 +72,7 @@ You can connect to the managed Postgres instance using the name of your service
 
 ```
 
+<!-- 
 ### Major Version Updating of Engine
 
 To update the database engine you can simply update the image to a later version in your compose file and apply it via ```defang compose up --provider=aws```. In the example below, we change from Postgres 15 to 16.
@@ -85,4 +89,4 @@ to
 ```
 database:
   image: postgres:16
-```
+``` -->

docs/faq.md

@@ -13,23 +13,47 @@ description: Frequently asked questions about Defang.
 
 ### Can I bring my own AWS or other cloud account?
 
-- Yes! Please check out the [Defang BYOC](./concepts/defang-byoc.md) documentation for more information.
+- Yes! Defang makes it easy to deploy your application to your own cloud account. Please check out the [Defang BYOC](./concepts/defang-byoc.md) documentation for more information.
 
 ### On AWS, can I deploy to services such as EC2, EKS, or Lambda?
 
 - The current release includes support for containers only, deployed to ECS. We are still exploring how to support additional execution models such as VMs and functions-as-a-service. However, using our Pulumi provider, it is possible to combine Defang services with other native AWS resources.
 
 ### Can I access AWS storage services such as S3 or database services such as RDS? How?
 
-- Yes, you can access whatever other resources exist in the cloud account you are using as a [Defang BYOC](./concepts/defang-byoc.md) Provider.
+- Yes, you can access AWS services in the AWS Dashboard as you normally would when you are [deploying to your AWS account](./providers/aws) using Defang. In fact, you can access whatever other resources exist in the cloud account you are using for [Defang BYOC](./concepts/defang-byoc.md).
 
-### Do you plan to support other clouds?
+### Can I run production apps with Defang?
 
-- While we currently support AWS as a [Defang BYOC](./concepts/defang-byoc.md) Provider, we plan to support other clouds in future releases, such as [Azure](./providers/azure.md) and [GCP](./providers/gcp.md).
+- Yes! Defang makes it easy to deploy your app on production-ready infrastructure in your own cloud account. For example, you can deploy your app to AWS with `defang up --provider=aws --mode=production`. Check out your preferred cloud provider on [Defang BYOC](./concepts/defang-byoc.md).
 
-### Can I run production apps with Defang?
+### Does Defang support blue/green deployments?
+
+- Defang does not currently support Blue/Green deploys, but it does support rolling updates with the `production` deployment mode. `defang up --mode=production`.
+
+### Does Defang support rolling deployments?
+
+- Yes! Defang supports rolling updates with the `production` deployment mode. `defang up --mode=production`.
+
+### Can I cancel a deployment once it has started?
+
+- No. Once a deployment has started, it cannot be canceled. However, you can always deploy a new version of your app which will replace the current deployment.
+
+### Will deploying a new version of my app cause downtime?
+
+- If you have deployed your application with the `--mode=production` flag, Defang will use the _production_ deployment mode. This mode will provision your app with multiple replicas and will perform a rolling update to ensure zero downtime. If you use another deployment mode, you may experience downtime during the deployment, as defang will not provision multiple replicas to save cost.
+
+### Can I deploy multiple services at once?
+
+- Yes! You can deploy multiple services at once by defining them in a single compose.yaml file. When you run `defang compose up`, Defang will deploy all the services defined in the file at once.
+
+### Can I deploy a service that depends on another service?
+
+- Defang does not currently support service dependencies. All services will be deployed simultaneously. Defang will however run multiple healthchecks before marking a service as healthy and spinning down any previously deployed services when using the `production` deployment mode.
+
+### Do you plan to support other clouds?
 
-- The [Defang Playground](./concepts/defang-playground.md) is meant for testing and trial purposes only. Deployment of productions apps with [Defang BYOC](./concepts/defang-byoc.md) is not yet supported and disallowed by the [Terms of Service](https://defang.io/terms-service.html). If you are interested in running production apps, please [contact us](https://defang.io/#Contact-us).
+- While we currently support [AWS](./concepts/defang-byoc#aws) for production and [DigitalOcean](./concepts/defang-byoc#digitalocean) in preview, we plan to support other clouds in future releases, such as [GCP](./providers/gcp.md) and [Azure](./providers/azure.md).
 
 ### I'm having trouble running the binary on my Mac. What should I do?
 

docs/getting-started/getting-started.md

@@ -102,11 +102,11 @@ Congratulations! You've successfully deployed your first service with Defang. No
 
 Defang supports various ways of creating and deploying services to the cloud. The following tutorials dive into each one in more detail:
 
+1. [Deploy to your own cloud](/docs/tutorials/deploy-to-your-cloud)
 1. [Update the code and redeploy](/docs/getting-started/build-and-deploy)
-2. [Monitor your services](/docs/getting-started/monitor)
-3. [Deploy an outline using AI](/docs/tutorials/generate-new-code-using-ai)
-4. [Build and deploy your code](/docs/tutorials/deploy-code-compose)
-5. [Deploy existing containers](/docs/tutorials/deploy-container-using-the-cli)
-6. [Deploy using Pulumi](/docs/tutorials/deploy-using-pulumi)
+1. [Monitor your services](/docs/getting-started/monitor)
+1. [Deploy an outline using AI](/docs/tutorials/generate-new-code-using-ai)
+1. [Deploy existing containers](/docs/tutorials/deploy-container-using-the-cli)
+1. [Deploy using Pulumi](/docs/tutorials/deploy-using-pulumi)
 
 Choose the direction that seems the most interesting. If you have any questions, join the [Defang Discord](https://discord.gg/defang) and we'll be happy to help you out.

docs/intro.md

@@ -1,15 +1,16 @@
 ---
 sidebar_position: 100
 title: Overview
-description: Overview of Defang, a radically simpler way to build, deploy, and optimize production-ready cloud apps.
+description: Overview of Defang, a radically simpler way to develop, deploy, and debug production-ready cloud apps.
 ---
 
+<iframe width="560" height="315" src="https://www.youtube.com/embed/afglsBYieuc?si=iKgUX4ejz7AixxqQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
 ### What is Defang?
 
 Defang is a radically simpler way for developers to develop, deploy, and debug their cloud applications. Defang enables you to easily author cloud application in any language, build and deploy to the cloud with a single command, and iterate quickly with AI-assisted tooling.
 
-- The [Defang CLI](./getting-started/installing.md) includes an AI-driven assistant that translates natural language prompts to an outline for your project that you can then refine.
+- The [Defang CLI](./getting-started/installing.md) includes an AI-driven agent that translates natural language prompts to an outline for your project that you can then refine.
 - Defang can automatically build and deploy your project with a single command.
     - If you’re new to Defang, you can try deploying to the [Defang Playground](./concepts/defang-playground.md), a hosted environment to learn to use Defang with non-production workloads.
     - Once you’re ready, you can [deploy](./concepts/deployments.md) it to your own cloud account - we call this [Defang BYOC](./concepts/defang-byoc.md). Defang takes care of all the heavy lifting such as configuring networking, security, [observability](./concepts/observability.md) and all the other details that usually slow down the average cloud developer.
@@ -21,8 +22,8 @@ Defang provides a streamlined experience to develop, deploy, observe, and update
 
 - Support for [various types of applications](./use-cases/use-cases.md): Web services and APIs, mobile app backends, ML services, hosting LLMs, etc.
 - Support for your programming [language of choice](./samples.md): Node.js, Python, Golang, or anything else you can package in a Dockerfile.
-- Built-in AI assistant to go [from natural language prompt to an outline project](./concepts/generate.md)
-- Built-in AI assistant to help you [debug your cloud applications](./concepts/debug.md)
+- Built-in AI agent to go [from natural language prompt to an outline project](./concepts/generate.md)
+- Built-in AI agent to help you [debug your cloud applications](./concepts/debug.md)
 - Automated [Dockerfile builds](./concepts/deployments.md)
 - Support for [pre-built Docker containers](./tutorials/deploy-container-using-the-cli.mdx), from public or private image registries
 - Ability to express your project configuration using a [Docker Compose YAML](./concepts/compose.md) file
@@ -31,4 +32,3 @@ Defang provides a streamlined experience to develop, deploy, observe, and update
 - [One-command deployments](./getting-started/installing.md)
 - Support for [GPUs](./concepts/resources.md)
 - Support for Infra-as-Code via the [Defang Pulumi provider](./concepts/pulumi.md)
-

docs/providers/_category_.json

@@ -1,8 +1,8 @@
 {
   "label": "Providers",
-  "position": 350,
+  "position": 400,
   "link": {
     "type": "generated-index",
     "description": "Defang allows you to use your own cloud accounts to deploy your applications. Click on a link below to read documentation about specific providers."
   }
-}
+}

docs/providers/aws/aws.md

@@ -17,7 +17,7 @@ Why should you use Defang with AWS? Defang allows you to easily create and manag
 Getting started with the Defang BYOC AWS Provider is easy. The first step is to [authenticate your shell](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) with AWS as an admin user. The authenticated user should be an IAM admin because Defang will need permission to create resources and IAM roles in your account.
 
 :::tip
-If you have the aws CLI installed, you should be able to successfully run `aws sts get-caller-identity` and see your account ID.
+If you have the AWS CLI installed, you should be able to successfully run `aws sts get-caller-identity` and see your account ID.
 :::
 
 Use the `--provider=aws` flag to tell the Defang CLI to use the AWS Provider or set the `DEFANG_PROVIDER` environment variable to `aws`.