From 1e1cef9ca990f0f6fd6146093b5880f111629b99 Mon Sep 17 00:00:00 2001 From: Raphael Titsworth-Morin Date: Wed, 7 Feb 2024 12:52:02 -0800 Subject: [PATCH] Update Defang Playground references --- docs/concepts/accounts.md | 18 ++++++++++- docs/concepts/compose.md | 12 ++++--- docs/concepts/configuration.md | 8 +++-- docs/concepts/defang-byoc.md | 2 +- docs/concepts/defang-hosted.md | 26 --------------- docs/concepts/defang-playground.md | 26 +++++++++++++++ docs/concepts/deployments.md | 7 ++-- docs/concepts/observability.md | 4 +++ docs/concepts/portal.md | 2 +- docs/concepts/pulumi.md | 12 +++---- docs/concepts/resources.md | 6 +++- docs/concepts/secrets.md | 14 ++++++-- docs/concepts/services.md | 12 ++++++- docs/getting-started/getting-started.md | 2 +- docs/getting-started/monitor.md | 2 +- docs/intro.md | 32 +++++++++++-------- docs/providers/aws.md | 4 +-- docs/tutorials/deploy-code-compose.mdx | 2 +- docs/tutorials/generate-new-code-using-ai.mdx | 2 +- 19 files changed, 126 insertions(+), 67 deletions(-) delete mode 100644 docs/concepts/defang-hosted.md create mode 100644 docs/concepts/defang-playground.md diff --git a/docs/concepts/accounts.md b/docs/concepts/accounts.md index 573ab2bac..5e9334d36 100644 --- a/docs/concepts/accounts.md +++ b/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: ``` ---.prod1.defang.dev diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index 78ccd5748..17e7860f9 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -10,9 +10,9 @@ 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 @@ -20,7 +20,7 @@ One thing to keep in mind is that, at the time of this writing, Defang identifie ## 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 -``` \ No newline at end of file +``` + +:::info Configuration & Secrets +Read more about configuration in the [configuration page](./configuration.md) and about secrets in the [secrets page](./secrets.md). +::: \ No newline at end of file diff --git a/docs/concepts/configuration.md b/docs/concepts/configuration.md index 8c7009d49..521096274 100644 --- a/docs/concepts/configuration.md +++ b/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. \ No newline at end of file +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). +::: \ No newline at end of file diff --git a/docs/concepts/defang-byoc.md b/docs/concepts/defang-byoc.md index d62f8cf54..ebfb14be2 100644 --- a/docs/concepts/defang-byoc.md +++ b/docs/concepts/defang-byoc.md @@ -6,7 +6,7 @@ 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. 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. diff --git a/docs/concepts/defang-hosted.md b/docs/concepts/defang-hosted.md deleted file mode 100644 index d890f1fad..000000000 --- a/docs/concepts/defang-hosted.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Defang Hosted -description: Defang Hosted allows you to get a feel for how Defang works without running production workloads in your own cloud accounts. -sidebar_position: 00 ---- - -# Defang Hosted - -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 Hosted, but it is only intended for non-production workloads so you can get a feel for how Defang works. - -Defang Hosted 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 Hosted. These limitations are in place to ensure that Defang Hosted 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 Hosted, it will be assigned a domain under the `defang.dev` domain. We do not support pointing your own domains to Defang Hosted services. - -### Max Resources - -* Services: 5 -* CPUs: 2 -* Memory: 8GB -* Replicas: 2 \ No newline at end of file diff --git a/docs/concepts/defang-playground.md b/docs/concepts/defang-playground.md new file mode 100644 index 000000000..a9c6005c5 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/concepts/deployments.md b/docs/concepts/deployments.md index a20c41fc1..25b58e1d6 100644 --- a/docs/concepts/deployments.md +++ b/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. \ No newline at end of file +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. +::: \ No newline at end of file diff --git a/docs/concepts/observability.md b/docs/concepts/observability.md index 7f9cd2189..a9ca5dad1 100644 --- a/docs/concepts/observability.md +++ b/docs/concepts/observability.md @@ -10,6 +10,10 @@ 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. diff --git a/docs/concepts/portal.md b/docs/concepts/portal.md index 3cdb12831..16df3fe49 100644 --- a/docs/concepts/portal.md +++ b/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. diff --git a/docs/concepts/pulumi.md b/docs/concepts/pulumi.md index cb681b0a3..2cab36821 100644 --- a/docs/concepts/pulumi.md +++ b/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/): ```bash -npm i @pulumi/pulumi +npm i @defang-io/pulumi-defang ``` ```bash -pnpm i @pulumi/pulumi +pnpm i @defang-io/pulumi-defang ``` ```bash -yarn add @pulumi/pulumi +yarn add @defang-io/pulumi-defang ``` diff --git a/docs/concepts/resources.md b/docs/concepts/resources.md index e8634afed..7b600b886 100644 --- a/docs/concepts/resources.md +++ b/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. +::: + diff --git a/docs/concepts/secrets.md b/docs/concepts/secrets.md index ac4143fc6..a5cb50bad 100644 --- a/docs/concepts/secrets.md +++ b/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. \ No newline at end of file +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) diff --git a/docs/concepts/services.md b/docs/concepts/services.md index 1d9fc965b..72a6cda51 100644 --- a/docs/concepts/services.md +++ b/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: + +`-` + +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. diff --git a/docs/getting-started/getting-started.md b/docs/getting-started/getting-started.md index 3f501e451..e8817a8c7 100644 --- a/docs/getting-started/getting-started.md +++ b/docs/getting-started/getting-started.md @@ -51,7 +51,7 @@ By default, all the output (stdout and stderr) from your app is logged. You can :::info * To learn more about observability in Defang, check out the [observability page](../concepts/observability.md). -* Note that the Defang Portal only displays services deployed to Defang Hosted. +* Note that the Defang Portal only displays services deployed to Defang Playground. ::: diff --git a/docs/getting-started/monitor.md b/docs/getting-started/monitor.md index 22395b3b3..21c949c80 100644 --- a/docs/getting-started/monitor.md +++ b/docs/getting-started/monitor.md @@ -21,5 +21,5 @@ By default, all the output (stdout and stderr) from your app is logged. You can :::info * To learn more about observability in Defang, check out the [observability page](../concepts/observability.md). -* Note that the Defang Portal only displays services deployed to Defang Hosted. +* Note that the Defang Portal only displays services deployed to Defang Playground. ::: \ No newline at end of file diff --git a/docs/intro.md b/docs/intro.md index 55e6bc55b..350d00818 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -5,26 +5,30 @@ description: Overview of Defang, a radically simpler way to build, deploy, and o --- -# Overview +### What is Defang? -### What is the Defang? +Defang is a radically simpler way for developers to build, deploy their apps to the cloud. Defang enables you to easily author cloud application in any language, build and deploy to the cloud with a single command, and iterate quickly. -Defang is a radically simpler way to build, deploy, and optimize production-ready cloud apps. Defang is a serverless platform that lets you quickly build your application in the language of your choice and deploy it to the cloud with a single command. The [Defang CLI](./getting-started/installing.md) includes an AI-driven assistant that translates natural language prompts to a starting point for your project that you can then refine. Once you publish your code, Defang automatically builds your project and deploys it to a pre-provisioned environment in the cloud, taking care of all the heavy lifting such as configuring networking, security, observability and all the other details that usually slow down the average cloud developer. +- 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. +- 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. +- You can also use Defang to easily publish updates to your deployed application with zero downtime. ### Details -The DOP provides a unified experience to develop, deploy, run, observe, and optimize your cloud applications. The DOP includes the following: +Defang provides a streamlined experience to develop, deploy, observe, and update your cloud applications. Defang includes the following features: - Support for various types of applications: Web services and APIs, mobile app backends, ML services, etc. -- Support for your programming language of choice: Node.js, Python, Golang, etc. -- Built-in AI assistant to go from natural language prompt to a skeleton project -- Automated build directly from your source code +- Support for your programming language of choice: 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 +- Automated Dockerfile builds - Support for pre-built Docker containers, from public or private image registries -- Ability to express your project configuration using a Docker Compose YAML file -- Pre-configured production environment with built-in networking, security, and observability -- One-command deploy to your production environment -- Support for GPUs -- Support for Infra-as-Code via a Pulumi provider -- Support for any cloud storage in the underlying cloud or any remote database service -- Built-in observability through hierarchical logging +- Ability to express your project configuration using a [Docker Compose YAML](./concepts/compose.md) file +- Ability to manage encrypted [secrets](./concepts/secrets.md) and [configuration](./concepts/configuration.md) +- Pre-configured, secure environments with built-in networking, IAM roles, and observability +- One-command deployments +- Support for [GPUs](./concepts/resources.md) +- Support for Infra-as-Code via the [Defang Pulumi provider](./concepts/pulumi.md) +- Built-in observability diff --git a/docs/providers/aws.md b/docs/providers/aws.md index 2bf971120..2e1524223 100644 --- a/docs/providers/aws.md +++ b/docs/providers/aws.md @@ -28,9 +28,9 @@ The Defang CLI does not depend on the AWS CLI. It uses the [AWS SDK for Go](http Defang uses resources that are native to the cloud provider you are using. The following describes the current state of Defang's support for AWS, the specific resources that Defang uses, and the roadmap for future support. -### Configuration +### Secrets -Defang allows you to configure your services with secrets. Secrets are stored in AWS Systems Manager Parameter Store, and are encrypted using AWS Key Management Service (KMS). The Defang CLI automatically creates a KMS key and a Parameter Store hierarchy for your services. +Defang allows you to configure your services with secrets. Secrets are stored in AWS Systems Manager Parameter Store, and are encrypted. ### Deployment diff --git a/docs/tutorials/deploy-code-compose.mdx b/docs/tutorials/deploy-code-compose.mdx index bdfdd5973..4f01a7bb2 100644 --- a/docs/tutorials/deploy-code-compose.mdx +++ b/docs/tutorials/deploy-code-compose.mdx @@ -63,7 +63,7 @@ services: # Step 4 - Deploy -Now that we have the code and the Docker Compose file, we can deploy the service using the `defang compose up` command. This will bundle the code into a container and deploy it with Defang. If you have [cloud credentials configured](../concepts/defang-byoc), the service will be deployed to AWS. If you don't have AWS credentials set up, the service will be deployed to [Defang Hosted](../concepts/defang-hosted). +Now that we have the code and the Docker Compose file, we can deploy the service using the `defang compose up` command. This will bundle the code into a container and deploy it with Defang. If you have [cloud credentials configured](../concepts/defang-byoc), the service will be deployed to AWS. If you don't have AWS credentials set up, the service will be deployed to [Defang Playground](../concepts/defang-playground). ```sh defang compose up diff --git a/docs/tutorials/generate-new-code-using-ai.mdx b/docs/tutorials/generate-new-code-using-ai.mdx index f705a7202..4de05b7c7 100644 --- a/docs/tutorials/generate-new-code-using-ai.mdx +++ b/docs/tutorials/generate-new-code-using-ai.mdx @@ -5,7 +5,7 @@ sidebar_position: 50 # Create an outline using AI -Defang supports generating new project outlines using integration with an AI model. Using this feature, you can describe what you would like the service to do and the CLI will then generate a project skeleton with all the files required to make it work. +Defang supports generating new project outlines using integration with an AI model. Using this feature, you can describe what you would like the service to do and the CLI will then generate a project outline with all the files required to make it work. ## Step 1 - Create a new folder for the project