Merge pull request #19 from defang-io/byoc

BYOC Update

docs/concepts/accounts.md

@@ -6,7 +6,23 @@ sidebar_position: 100
 
 # Accounts
 
-At the moment, Defang only allows authentication through GitHub. This means that you will need to have a GitHub account to use the system, but it also means that your GitHub username will be used as your Defang username. Your Defang username is used to group all your services and to generate domains for your services with the following structure:
+In this section, we'll be talking about a couple different topics related to accounts in Defang. First we'll cover authentication and how to create an account, and then we'll talk about how resources are organized within a cloud environment using your account info.
+
+:::tip Why do I need an account?
+Defang requires an account so we can organize your resources and provide you with a way to manage them. We also use your account to authenticate you when you interact with [Defang Playground](./defang-playground.md) and the [Defang Portal](./portal.md).
+
+Eventually, billing and payment information will be associated with your account.
+:::
+
+## Creating an Account
+
+To create an account, simply login to Defang and accept the [terms of service](https://defang.io/terms-service.html) using the [CLI](../getting-started/authenticating.md).
+
+At the moment, the only way to authenticate with Defang is through GitHub. We plan to offer other authentication providers in the future.
+
+## Structure
+
+Your GitHub username will be used as your Defang username and your Defang username is used to group all your services and to generate domains for your services with the following structure:
 
 ```
 <username>-<servicename>--<port>.prod1.defang.dev

docs/concepts/compose.md

@@ -10,17 +10,17 @@ You might be familiar with the [docker-compose.yml](https://docs.docker.com/comp
 
 ## How it works
 
-When you bootstrap a project with the `defang generate` command, it will generate a `docker-compose.yml` file in the root of your project. This file is used to define your application's services and how they run. You can edit this file to add more services or change the configuration of existing services.
+You can define your [services](./services.md) using a `docker-compose.yml` file in the root of your project, or use the [`defang generate` command](../tutorials/generate-new-code-using-ai.mdx) to generate one (along with other resources). This file is used to define your application's services and how they run. You can edit this file to add more services or change the configuration of existing services.
 
-When you run `defang up`, Defang will read your `docker-compose.yml` file and deploy the services named in that file to the cloud.
+When you run `defang up`, Defang will read your `docker-compose.yml` file and [deploy](./deployments.md) the services named in that file to the cloud.
 
 ## Service Name Resolution
 
 One thing to keep in mind is that, at the time of this writing, Defang identifies services by the [user/account name](./accounts.md) and the service name (as defined in the `docker-compose.yml` file). This means that if you have multiple Defang projects with the same service name, they will conflict with each other. We plan to provide a more robust system for managing service names and protecting against conflicts in the future.
 
 ## Configuration
 
-If you have a service that depends on a secret like an api key, you can set that secret using the CLI:
+If you have a service that depends on a secret like an api key, you can set that [secret](./secrets.md) using the CLI:
 
 ```
 defang secret set --name MY_API_KEY
@@ -33,4 +33,8 @@ services:
   my-service:
     secrets:
       - MY_API_KEY
-```
+```
+
+:::info Configuration & Secrets
+Read more about configuration in the [configuration page](./configuration.md) and about secrets in the [secrets page](./secrets.md).
+:::

docs/concepts/configuration.md

@@ -6,6 +6,10 @@ sidebar_position: 350
 
 # Configuration
 
-Defang allows you to configure your application using environment variables. You can set environment variables in your `docker-compose.yml` file, or in your Pulumi program. 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 [`docker-compose.yml` 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.
 
-You can also use [secrets](./secrets.md) to store sensitive information like API keys and database passwords.
+You can also use [secrets](./secrets.md) to store sensitive information like API keys and database passwords.
+
+:::tip Sample
+You can find a sample of how to set environment variables with Pulumi [here](https://github.com/defang-io/defang/tree/main/samples/nodejs/remix-aiven-postgres).
+:::

docs/concepts/defang-byoc.md

@@ -1,14 +1,19 @@
 ---
 title: Defang BYOC
 description: Defang allows you deploy services, defined as containers, to your own cloud accounts.
-sidebar_position: 000
+sidebar_position: 50
 ---
 
 # Defang BYOC
 
-Defang aims to 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 Hosted, but it is only intended for non-production workloads so you can get a feel for how Defang works.
+Defang aims to 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.
 
-To the extent possible, Defang will use resources that are native to the cloud provider you are using. 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/), 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.
+
+:::info
+Defang does not install or run any Defang or third party services at runtime.
+Defang does run the Defang build service to build your container images, which terminates after every build.
+:::
 
 ## AWS
 

docs/concepts/defang-playground.md

@@ -0,0 +1,26 @@
+---
+title: Defang Playground
+description: Defang Playground allows you to get a feel for how Defang works without running production workloads in your own cloud accounts.
+sidebar_position: 00
+---
+
+# Defang Playground
+
+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) which you can read about in more depth [here](./defang-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 Playground is a free tier that allows you to deploy services to a Defang-hosted cloud account without needing to manage your own. It is intended for non-production workloads only.
+
+## Limitations
+
+There are a few limitations to Defang Playground. These limitations are in place to ensure that Defang Playground is only used for non-production workloads. If you are interested in running production workloads, you should use Defang BYOC.
+
+### No Custom Domain Support
+
+When you deploy a service to Defang Playground, it will be assigned a domain under the `defang.dev` domain. We do not support pointing your own domains to Defang Playground services.
+
+### Max Resources
+
+* Services: 5
+* CPUs: 2
+* Memory: 8GB
+* Replicas: 2

docs/concepts/deployments.md

@@ -6,5 +6,8 @@ sidebar_position: 250
 
 # Deployment
 
-When you deploy to Defang, whether it's with `defang compose up` or using a Pulumi program, Defang will build your services in the cloud and manage the deployment process for you. If you provide a Dockerfile and build context, Defang will upload the files found within the 
-context, build the image, and store it in the [cloud provider's](./defang-byoc) container registry. Defang will also make sure to get your new service up and running before deprovisioning any old services so you don't have to worry about downtime.
+When you deploy using Defang, whether it's with `defang compose up` with a [compose file](./compose.md) or using a [Pulumi program](./pulumi.md), Defang will build your services in the cloud and manage the deployment process for you. If you provide a Dockerfile and build context, Defang will upload the files found within the build context to the cloud (either yours in [Defang BYOC](./defang-byoc.md) or ours in [Defang Playground](./defang-playground.md)), build the image, and store it in the cloud provider's container registry. Defang will also make sure to get your new service up and running before deprovisioning any old services so you don't have to worry about downtime.
+
+:::info
+In [Defang BYOC](./defang-byoc.md), Defang will use your cloud provider account to build and store your images. In [Defang Playground](./defang-playground.md) we will build and store your images for you.
+:::

docs/concepts/observability.md

@@ -10,11 +10,19 @@ You can easily monitor and debug your Defang services at build and runtime using
 
 When you deploy a service using the `defang 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.
+:::
+
 ## Tail
 
 The `defang tail` command will tail the logs for all your services by default. You can also specify a service `--name` to tail the logs for a specific service. If you specify the `--etag` the CLI will only tail the logs for a specific build of a service.
 
 ```
 defang tail --name my-service
 defang tail --etag ua119053ehi2
-```
+```
+
+## Architecture
+
+In [BYOC](./defang-byoc.md), output is logged to the native logging tools within your cloud provider. The CLI then tails the output as needed.

docs/concepts/portal.md

@@ -6,7 +6,7 @@ sidebar_position: 700
 
 # Portal
 
-You can log into the Defang portal at [portal.defang.dev](https://portal.defang.dev) to view the state of your Defang services running on the hosted Defang platform for non-production applications.
+You can log into the Defang portal at [portal.defang.dev](https://portal.defang.dev) using your [Defang account](./accounts.md) to view the state of your Defang services running in the Defang Playground for non-production applications.
 
 You can use the portal to get an overview of your services, view the logs for each service, quickly access exposed ports, view environment variables, and more.
 

docs/concepts/pulumi.md

@@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem';
 # Pulumi
 
 :::warning
-Pulumi support is currently only available for Defang Hosted. We are working on support for Defang BYOC.
+Pulumi support is currently only available for Defang Playground. We are working on support for Defang BYOC.
 :::
 
 You can use Pulumi to define your Defang services. This allows you to integrate your Defang services with other cloud resources.
@@ -19,29 +19,29 @@ For example, you might define an Aiven PostgreSQL database in your Pulumi code a
 
 It also allows you to manage configuration for different environments using Pulumi's config system.
 
-## Provider
+## Defang Pulumi Provider
 
-To get started with Pulumi and Defang you will need to install the Defang provider:
+To get started with Pulumi and Defang you will need to install the Defang provider in [your Pulumi project](https://www.pulumi.com/learn/pulumi-fundamentals/create-a-pulumi-project/):
 
 <Tabs>
   <TabItem value="npm" label="npm" default>
 
 ```bash
-npm i @pulumi/pulumi
+npm i @defang-io/pulumi-defang
 ```
 
   </TabItem>
   <TabItem value="pnpm" label="pnpm">
 
 ```bash
-pnpm i @pulumi/pulumi
+pnpm i @defang-io/pulumi-defang
 ```
 
   </TabItem>
   <TabItem value="yarn" label="yarn">
 
 ```bash
-yarn add @pulumi/pulumi
+yarn add @defang-io/pulumi-defang
 ```
 
   </TabItem>

docs/concepts/resources.md

@@ -15,8 +15,8 @@ You can configure the resources available to your Defang services as required. Y
 ```yaml
 services:
   gpu-service:
-    scale: 3
     deploy:
+      replicas: 3
       resources:
         reservations:
           cpus: '1.0'
@@ -42,3 +42,7 @@ const service = new defang.DefangService("gpu-service", {
 });
 ```
 
+:::info GPUs
+If you require access to GPUs, you can specify this in the `deploy.resources.reservations.devices[0].capabilities` section of your service as in the examples above. You can learn more about this in the [docker-compose documentation](https://docs.docker.com/compose/gpu-support/). This is the only supported value in the `deploy.resources.reservations.devices` section.
+:::
+

docs/concepts/secrets.md

@@ -6,10 +6,20 @@ sidebar_position: 300
 
 # Secrets
 
-The Defang CLI allows you to securely store sensitive information such as API keys, passwords, and other credentials. This information is stored securely, encrypted in AWS Systems Manager parameter store.
+The Defang CLI allows you to securely store sensitive information such as API keys, passwords, and other credentials.
 
 You can use secrets by specifying them in the `secrets` section of a service in a `docker-compose.yml` file, or by specifying a secret in your Pulumi code.
 
 ## 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. If you are using the Pulumi-based workflow you will need to redeploy using Pulumi.
+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 secrets [here](https://github.com/defang-io/defang/tree/main/samples/nodejs/ChatGPT%20API).
+:::
+
+## Providers
+
+Here are the different ways secrets are stored depending on the provider you are using:
+
+    * [AWS](../providers/aws.md#secrets)

docs/concepts/services.md

@@ -6,7 +6,17 @@ sidebar_position: 200
 
 # Services
 
-At the moment, all services deployed with Defang are containerized. This means that you can use any container image from Docker Hub or any other container registry, including private registries. You can also use a local Dockerfile: when you run `defang compose up` or run your [Pulumi program](./pulumi.md), Defang will package your application source and upload it to the cloud to run the build process.
+Defang allows you deploy services defined as containers. You can define your services using a [compose file](./compose.md) or a [Pulumi program](./pulumi.md). Services can be exposed to the internet or kept private, and can communicate between themselves using the following conventions for hostnames:
+
+`<username>-<service-name>`
+
+You can learn more about accounts and usernames in the [accounts page](./accounts.md).
+
+:::tip Service Names
+Service names are defined in your compose file or your Pulumi program.
+:::
+
+You can learn more about about how to define [services with compose files here](./compose.md) and [services with Pulumi here](./pulumi.md). You can learn more about how services are deployed in the [deployment page](./deployments.md).
 
 :::info
 While this is the current state of the Defang model, we plan to add support for other types of services in the future, including serverless functions.

docs/faq.md

@@ -7,26 +7,26 @@ description: Frequently asked questions about Defang.
 
 # FAQ
 
-### **Which cloud/region is the app being deployed to?**
+### Which cloud/region is the app being deployed to?
 
 - Currently we are deploying to AWS us-west-2.
 
-### **Can I bring my own AWS or other cloud account?**
+### Can I bring my own AWS or other cloud account?
 
 - With the current release, which is designed for customers to try out the Defang model with non-production apps, your apps are deployed to Defang’s AWS account. We are working on bring-your-own-account for an upcoming release.
 
-### **On AWS, can I deploy to services such as EC2, EKS, or Lambda?**
+### On AWS, can I deploy to services such as EC2, EKS, or Lambda?
 
 - The current release includes support for containers only, deployed to ECS. Future releases shall include support for Lambda, EC2 etc. 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?**
+### Can I access AWS storage services such as S3 or database services such as RDS ? How?
 
 - Yes, you can access any storage service from the underlying cloud platform (AWS) or from a remote database service. To secure access from your Defang services, you should use our published public IPs in your AWS security group or IP allow list.
 
-### **Do you plan to support other clouds?**
+### Do you plan to support other clouds?
 
 - While we currently deploy to AWS, the Defang model is designed to be inherently portable. We plan to support other clouds in future releases.
 
-### **Can I run production apps on DOP?**
+### Can I run production apps on DOP?
 
 - The current release of DOP is meant for testing and trial purposes only. Deployment of productions apps is not supported and explicitly disallowed by the [Terms of Service](https://defang.io/terms-service.html).

docs/getting-started/build-and-deploy.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 300
+title: Build & Deploy Services
+description: Build and deploy services with Defang.
+---
+
+
+# Build and Deploy Services
+
+Defang supports various ways of creating and deploying services to the cloud. The following tutorials dive into each one in more detail:
+
+1. [Create an outline using AI](../tutorials/generate-new-code-using-ai.mdx)
+2. [Build and deploy your code](../tutorials/deploy-code-compose.mdx)
+3. [Deploy an existing container](../tutorials/deploy-container-using-the-cli.mdx)
+4. [Deploy using Pulumi](../tutorials/deploy-using-pulumi.mdx)
+