Merge pull request #146 from DefangLabs/linda-docs-6

More fixes + improvements

Author: commit111

blog/2024-03-20-dev-environments.mdx

@@ -15,7 +15,7 @@ We want it to be easy for you to try Defang with as little friction as possible,
 
 ## Codespaces
 
-If you want to get started with Codespaces, you can just fork [this repo](https://github.com/DefangLabs/github-codespace). It comes with the Defang CLI pre-installed so you can start playing with it immediately. It's setup using the Defang CLI [Dev Container Feature](https://github.com/DefangLabs/devcontainer-feature/pkgs/container/devcontainer-feature%2Fdefang-cli).
+If you want to get started with Codespaces, you can just fork [this repo](https://github.com/DefangLabs/github-codespace). It comes with the Defang CLI pre-installed so you can start playing with it immediately. It's set up using the Defang CLI [Dev Container Feature](https://github.com/DefangLabs/devcontainer-feature/pkgs/container/devcontainer-feature%2Fdefang-cli).
 
 ## Dev Containers
 

blog/2024-11-12-hard-lessons-from-hardware.md

@@ -41,7 +41,7 @@ This is what the Flask server looked like on my computer as it got pinged:
 
 Hooray! Once everything was working, It was time to deploy my Flask code as a cloud service so I could access it from any computer, not just my own. Deployment usually takes several hours due to configuring a ton of cloud provider settings. But I ain’t got time for that. Instead, I used Defang to deploy it within minutes, which took care of all that for me. Saved me a lot of time and tears.
 
-Here’s the Flask deployment on Defang’s portal view: 
+Here’s the Flask deployment on Defang’s Portal view: 
 
 ![portal_view](/img/hardware-story/portal_view.png)
 

docs/concepts/configuration.md

@@ -6,13 +6,9 @@ sidebar_position: 225
 
 # Configuration
 
-Defang allows you to configure your application using environment variables. You can set environment variables in your [`compose.yaml` file](./compose.md), or in your [Pulumi program](./pulumi.md). Using Pulumi gives you the advantage of being able to manage your environment variables across different environments using Pulumi stacks.
+Defang allows you to configure your application using environment variables. You can set environment variables in your [`compose.yaml` file](./compose.md), or in your [Pulumi program](#using-config-with-pulumi).
 
-:::tip Sample
-You can find a sample of how to set environment variables with Pulumi [here](https://github.com/DefangLabs/defang/tree/main/samples/nodejs/remix-aiven-postgres).
-:::
-
-# Sensitive Config aka Secrets
+# Sensitive Config (aka Secrets)
 
 The Defang CLI allows you to securely store sensitive information such as API keys, passwords, and other credentials. To do so, run:
 
@@ -44,6 +40,10 @@ services:
 
 Use the `defang config` command of the Defang CLI to manage the values.
 
+:::tip
+You can find a sample of how to set sensitive config values [here](https://github.com/DefangLabs/samples/tree/main/samples/nodejs-openai).
+:::
+
 ## Interpolation
 
 Environment variables are set within the *environment* section of a service in a `compose.yaml` file. Any variables declared here will become available within the service container.
@@ -62,18 +62,24 @@ In the example above, if we assume the value of the configuration variable ***US
 
 During `defang compose up` all variable references will be replaced with the actual value and made available in the container. If any referenced variable is not found the `defang compose up` command will be canceled.
 
+## Using Config with Pulumi 
+In Defang, using config with [Pulumi](./pulumi.md) gives you the advantage of being able to manage your environment variables across different environments using Pulumi stacks.
+
+:::tip
+You can find a sample of how to set environment variables with Pulumi [here](https://github.com/DefangLabs/samples/tree/main/samples/pulumi-remix-postgres).
+:::
+
 ## Connecting Services
 
 If you have created a service before a secret you can connect it by running the `defang compose start` command if using the [`defang compose` workflow](./compose.md). If you are using the [Pulumi-based workflow](./pulumi.md) you will need to redeploy using Pulumi.
 
-:::tip Sample
-You can find a sample of how to set sensitive config values [here](https://github.com/DefangLabs/defang/tree/main/samples/nodejs/ChatGPT%20API).
-:::
-
 ## Providers
 
 Here are the different ways sensitive config values are stored depending on the provider you are using:
 
     * [AWS](../providers/aws/aws.md#secrets)
+    * [DigitalOcean](../providers/digitalocean#secrets)
+    * [GCP](../providers/gcp#secrets)
+
 
 

docs/concepts/debug.md

@@ -6,16 +6,30 @@ sidebar_position: 650
 
 # Debug
 
-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.
+Defang includes an AI-driven tool in the CLI (command-line interface) 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 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.
+:::info
+Defang has another AI-driven tool called [`generate`](/docs/concepts/generate).
 :::
 
-## How it works
+## How It Works
+
+Here is a typical workflow in the [Defang CLI](/docs/getting-started) that will automatically run the AI debugger tool:
+
+1. When you deploy a project with Defang (i.e. `defang compose up`), the CLI will wait for all services' statuses to switch to healthy. 
+
+2. If any service fails to deploy, the AI debugger will kick in and ask for permission.
+
+3. The AI agent will analyze the logs and files in your project to identify the issue(s).
+
+4. Then, it will provide you with the suggested fix(es) in the terminal. 
+
+:::tip
+The AI debugger will not change your files. Instead, it will show you a suggestion, and it is up to you if you want to use it in your code.
+:::
 
-When you deploy a project with Defang, the CLI will wait for all services' statuses to switch to healthy. If any service fails to deploy, the AI debugger will kick in. It will analyze the logs and files in your project to identify the issue and provide you with a suggested fix. **The AI debugger will not change your files.**
+The AI debugger only kicks in when any service in a project fails to deploy. This could be because of a build failure, healthchecks failing, or a variety of other issues. 
 
 :::info
-The AI debugger only kicks in when any service in a project fails to deploy. This could be because of a build failure, healthchecks failing, or a variety of other issues. At the moment, we do not offer any way to trigger the AI debugger manually.
+The AI debugger only kicks in when any service in a project fails to deploy. At the moment, we do not offer any way to trigger the AI debugger manually. 
 :::

docs/concepts/defang-byoc.md

@@ -8,7 +8,7 @@ sidebar_position: 50
 
 Defang aims to make it easier to deploy your services to the cloud. Specifically, Defang's goal is to make it easier to deploy your workloads to your *own* cloud accounts. We refer to this as bring-your-own-cloud (BYOC). We also provide Defang Playground, but it is only intended for non-production workloads so you can get a feel for how Defang works.
 
-Defang provisions and configures the necessary native managed services from your cloud provider to get your services up and running. For example, on AWS, Defang will configure an [ALB](https://aws.amazon.com/elasticloadbalancing/application-load-balancer/), setup [ECR](https://aws.amazon.com/ecr/), configure [CloudWatch](https://aws.amazon.com/cloudwatch/?nc2=type_a), and run your service on [ECS](https://aws.amazon.com/ecs/?nc2=type_a) and more. The following lists the existing and planned support for cloud providers.
+Defang provisions and configures the necessary native managed services from your cloud provider to get your services up and running. For example, on AWS, Defang will configure an [ALB](https://aws.amazon.com/elasticloadbalancing/application-load-balancer/), set up [ECR](https://aws.amazon.com/ecr/), configure [CloudWatch](https://aws.amazon.com/cloudwatch/?nc2=type_a), and run your service on [ECS](https://aws.amazon.com/ecs/?nc2=type_a) and more. The following lists the existing and planned support for cloud providers.
 
 :::info
 Defang does not install or run any Defang or third party services at runtime.

docs/concepts/generate.md

@@ -8,12 +8,12 @@ sidebar_position: 100
 
 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#install-the-defang-cli.md).
 
+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).
+
 :::info
-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.
+This page is about Defang's AI tool for project outline generation. We also have an AI tool for [debugging](/docs/concepts/debug).
 :::
 
-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 agent can help you with:
@@ -45,5 +45,5 @@ An HTTP GET endpoint that returns an HTML with a random meme from the imgflip AP
 **An example of a more complex prompt**
 
 ```
-A service that uses bullmq and redis. The compose file should also include a redis service. The code should setup a queue. It should also expose three endpoints with express: one to add a job to the queue, another to check how many tasks are in the queue, and a last one that runs on / which is just a healthcheck. The code should also include a worker that processes the queue by logging what's in each task. Use environment variables to configure the redis connection. No password.
-```
+A service that uses bullmq and redis. The compose file should also include a redis service. The code should set up a queue. It should also expose three endpoints with express: one to add a job to the queue, another to check how many tasks are in the queue, and a last one that runs on / which is just a healthcheck. The code should also include a worker that processes the queue by logging what's in each task. Use environment variables to configure the redis connection. No password.
+```

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

@@ -16,6 +16,7 @@ Managed Object Storage, like AWS S3, is a service that allows you to store and r
 
 | Provider | Managed Object Storage |
 | --- | --- |
-| [Playground](/docs/providers/playground.md) | ❌ |
-| [AWS](/docs/providers/aws/aws.md) | ❌ |
-| [DigitalOcean](/docs/providers/digitalocean/digitalocean.md) | ❌ |
+| [Playground](/docs/providers/playground#managed-services) | ❌ |
+| [AWS](/docs/providers/aws#managed-storage) | ❌ |
+| [DigitalOcean](/docs/providers/digitalocean#future-improvements) | ❌ |
+| [GCP](/docs/providers/gcp#future-improvements) | ❌ |

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

@@ -12,9 +12,10 @@ Postgres, or PostgreSQL, is an advanced open-source relational database system k
 
 | Provider | Managed Postgres |
 | --- | --- |
-| [Playground](/docs/providers/playground) | ❌ |
-| [AWS](/docs/providers/aws/aws.md#managed-postgres) | ✅ |
-| [DigitalOcean](/docs/providers/digitalocean/digitalocean.md) | ❌ |
+| [Playground](/docs/providers/playground#managed-services) | ❌ |
+| [AWS](/docs/providers/aws#managed-storage) | ✅ |
+| [DigitalOcean](/docs/providers/digitalocean#future-improvements) | ❌ |
+| [GCP](/docs/providers/gcp#future-improvements) | ❌ |
 
 ## How to use Managed Postgres
 

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

@@ -12,9 +12,10 @@ Redis is an in-memory data structure store widely used for caching, real-time an
 
 | Provider | Managed Redis |
 | --- | --- |
-| [Playground](/docs/providers/playground.md#managed-redis) | ❌ |
-| [AWS](/docs/providers/aws/aws.md#managed-redis) | ✅ |
-| [DigitalOcean](/docs/providers/digitalocean/digitalocean.md) | ❌ |
+| [Playground](/docs/providers/playground#managed-services) | ❌ |
+| [AWS](/docs/providers/aws#managed-storage) | ✅ |
+| [DigitalOcean](/docs/providers/digitalocean#future-improvements) | ❌ |
+| [GCP](/docs/providers/gcp#future-improvements) | ❌ |
 
 ## How to use Managed Redis
 

docs/concepts/observability.md

@@ -8,7 +8,7 @@ sidebar_position: 600
 
 You can easily monitor and debug your Defang services at build and runtime using the Defang CLI and portal.
 
-When you deploy a service using the `defang compose up` the CLI will automatically start tailing the build and runtime logs for your service. You can also view the logs for your service in the portal, or by using the `defang tail` command.
+When you deploy a service using the `defang compose up`, the CLI will automatically start tailing the build and runtime logs for your service. You can also view the logs for your service in the portal, or by using the `defang tail` command.
 
 :::warning
 Keep in mind that the Defang Portal only displays services deployed to Defang Playground.