one click components

Author: raphaeltm

blog/2024-02-12-announcing-defang-public-beta.md

@@ -12,7 +12,7 @@ Ever since we shipped our Private Beta in the summer of 2023, we have been worki
 
 And so, today with our Public Beta, we are addressing this request. With today’s release of [Defang BYOC](https://docs.defang.io/docs/concepts/defang-byoc) (Bring-your-own-Cloud), you can now enjoy all the benefits of Defang **and** deploy applications to your own AWS account! Our Private Beta experience is still available as [Defang Playground](https://docs.defang.io/docs/concepts/defang-playground) for you to quickly and easily prototype applications and deploy them to our hosted environment.
 
-You can learn more about Defang [here](https://docs.defang.io/docs/intro). Also check out our [tutorials](https://docs.defang.io/docs/category/tutorials), [samples](https://docs.defang.io/docs/samples), and [FAQ](https://docs.defang.io/docs/category/faq) to know more.
+You can learn more about Defang [here](https://docs.defang.io/docs/intro). Also check out our [tutorials](https://docs.defang.io/docs/category/tutorials), [samples](https://defang.io/samples), and [FAQ](https://docs.defang.io/docs/category/faq) to know more.
 
 **Try the Public Beta!**
 

blog/2024-07-31-july-product-updates-2.md

@@ -11,21 +11,20 @@ Hey folks! We can’t believe a month has gone by already, time flies when you
 
 1.  As our user-base grows, we wanted to make sure we’re able to scale our [Playground](https://docs.defang.io/docs/concepts/defang-playground) environment to be able to handle the load. This involved being able to shard the workload across multiple ALBs and being able to dynamically move some workloads  across shards where possible. With these changes, we are now able handle a large number of concurrent users comfortably. The only noticeable change in behavior you would see is that Defang will now ask you to “`compose down`” your previous project before you are able to deploy a new project on Playground.
 
-2.  The major news this month was the introduction of our “`debug`” functionality. The motivation for this feature was that while the Defang experience is amazing when everything goes smoothly, we saw users (including our own interns who are helping write all those [samples](https://docs.defang.io/docs/samples)) struggle when they hit an error. The underlying reason for the error could come from a variety of sources: an error in the developer’s application (including in their Dockerfile or Compose file), an issue in the way Defang is processing the application, or an issue in the underlying cloud platform (currently, AWS). To the developer, it is often not obvious what the issue is or how to fix it. That got us thinking how we could make this debugging experience “radically simpler” and thus the idea for `defang debug` was born.
-    
+2.  The major news this month was the introduction of our “`debug`” functionality. The motivation for this feature was that while the Defang experience is amazing when everything goes smoothly, we saw users (including our own interns who are helping write all those [samples](https://defang.io/samples)) struggle when they hit an error. The underlying reason for the error could come from a variety of sources: an error in the developer’s application (including in their Dockerfile or Compose file), an issue in the way Defang is processing the application, or an issue in the underlying cloud platform (currently, AWS). To the developer, it is often not obvious what the issue is or how to fix it. That got us thinking how we could make this debugging experience “radically simpler” and thus the idea for `defang debug` was born.
+
     Now (with CLI v0.5.37 if your application encounters an error that leads to a failed deployment, a failed health-check, or a run-time error, Defang will automatically detect the issue. It will then offer to help you debug it by running the `defang debug`  command. If you choose to proceed, Defang will apply an LLM model to try to determine the precise cause of the error, with the context of your application source, logs, error code etc. And it will try to come up with one or more actionable insights on how to fix the error. For an example, see the case below:
-    
-    
-    
+
+
+
     Behind the scenes, Defang is having a conversation on your behalf with the LLM to narrow down to the cause of the error.  We would love for you to try the `debug` feature and give us your feedback so we can improve it further. One future improvement already on our list is the ability to, with user consent, automatically apply a chosen fix and re-try. We are also looking for way to improve the range of failures we are able to diagnose successfully.
 
 ## Townhall
 
 If you're excited about what's coming next and want to hear more about our vision for the future, join us for our Townhall on August 21st. We'll be sharing more about our roadmap and what we're working on next. We'll also be making sure to take time to answer any questions you have, hear your feedback, and learn more about what you want from Defang!
 
 **[Register here](https://lu.ma/rlj13eq5)**
-    
+
 ---
 
 We’re excited to keep improving Defang to make it the easiest way for you to Develop, Deploy, and Debug cloud application. Stay tuned for more updates next month.
-

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

@@ -60,4 +60,4 @@ Before I let you go, here are the hard lessons from hardware, from yours truly:
 4. Choose the simpler way if it is offered.
 5. That’s where Defang comes in.
 
-Want to try deploying to the cloud yourself? You can try it out [here](https://defang.io/#samples). Keep on composing up! 💪 
+Want to try deploying to the cloud yourself? You can try it out [here](https://defang.io/samples). Keep on composing up! 💪

docs/concepts/compose.md

@@ -6,35 +6,247 @@ sidebar_position: 150
 
 # Compose
 
-You might be familiar with `docker-compose.yml` files, now known as the [Compose specification](https://docs.docker.com/compose/compose-file/) and `compose.yaml` files. It's a simple way to define and run multi-container Docker applications. Defang allows you to use `compose.yaml` files to deploy your application to the cloud.
+Defang allows you to use `compose.yaml` files to deploy your application to the cloud. 
+The `compose.yaml` file is a simple way to define and run multi-container applications. 
+This file format may look familiar to you if you've used [Docker](https://docker.com).
 
-## How it works
+The [Compose Specification](https://github.com/compose-spec/compose-spec/blob/main/spec.md#compose-file) lets you define a platform-agnostic application designed as a set of containers which are configured to run together with shared resources. These applications may be destined for any [OCI](https://opencontainers.org/) Container Runtime. Defang does the heavy lifting to deploy to your favourite cloud platform using this file.
 
-You can define your [services](./services.md) using a `compose.yaml` 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.
+## How It Works
+
+You can create a `compose.yaml` file in the root of your project, or use the [`defang generate`](../tutorials/generate-new-code-using-ai.mdx) command to create one for you (along with other resources). This file is used to define your application's [services](./services.md) and how they run. You can edit this file to add more services or change the configuration of services.
 
 When you run `defang compose up`, Defang will read your `compose.yaml` file and [deploy](./deployments.md) the services named in that file to the cloud.
 
-## Service Name Resolution
+## Example of a Compose File
+Here is a basic `compose.yaml` file that contains all the required properties for deployment in Defang. 
+
+```yaml
+services:
+  service-example:
+    image: nginx:latest # use one of: image (shown on this line) or build (shown below)
+    # build: 
+    #   context: .
+    #   dockerfile: Dockerfile
+  ports: 
+    - mode: ingress # specify ports to expose
+      target: 8080
+      published: 8080 # this is useful for running locally
+        
+```
 
-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 `compose.yaml` 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.
+## Compose Top-level Properties
+Here are a list of top-level properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) that Defang supports when writing a `compose.yaml` file.
 
-## Configuration
+### `services`
+(Required)
 
-If you have a service that depends on a [config value](./configuration.md) (such as an API key), you can set it using the CLI:
+The services defined in your application. 
 
+```yaml
+services:
+  service:
+    # add service-level properties here
 ```
-defang config set MY_API_KEY
+
+:::info 
+Defang identifies a service based on your username, project name, and the service name you've defined under the `services` property. See our [Services](/docs/concepts/services) page for more about how Defang resolves service names.
+:::
+
+### `networks`
+(Optional)
+
+The networks defined in your application. This is commonly added together with a [service-level `networks`](#networks-1) property. 
+
+```yaml
+networks:
+  public: 
 ```
 
-and then connect it to the service by specifying it in the `compose.yaml`:
+See our [Networking](/docs/concepts/networking) page for more.
+
+### `volumes`
+(Not yet supported)
+
+The volume mounts for a container, reusable across services. This feature is not currently supported by Defang.
+
+```yaml
+# volumes:
+#   db-data:
+```
+
+:::warning
+Defang does not support the `secrets` top-level property. Please read our [Configuration](/docs/concepts/configuration) page for more. 
+:::
+
+## Compose Service-level Properties
+Here are a list of service-level properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) that Defang supports when writing a `compose.yaml` file.
+
+:::tip
+Service-level means inside your `service`. A service-level property called `build` would look like:
+```yaml
+service:
+    build: ...
+```
 
+Note that in your Compose file, you will need a top-level property called `services` to contain all of your services. For example:
 ```yaml
 services:
-  my-service:
-    environment:
-      - MY_API_KEY
+    service:
+        build: ...
+```
+:::
+
+### `build`
+(Required, unless `image` is defined)
+
+The [build configuration](https://github.com/compose-spec/compose-spec/blob/main/build.md). This property describes how to create an OCI container for this service.
+
+```yaml
+build:
+  context: .
+  dockerfile: ./Dockerfile
+```
+
+### `image`
+(Required, unless `build` is defined)
+
+[This property](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#image) describes the image from which your container should start.
+
+```yaml
+image: nginx:latest
+```
+
+### `ports`
+(Optional, but required if you want to access the service from outside the container)
+
+The ports to expose. The default port mode is `ingress`.
+
+```yaml
+ports:
+  - mode: ingress
+    target: 80
+    published: 80
+```
+
+:::info
+Defang ignores `published` ports in production. As such, it is common to make `target` and `published` ports the same when using Defang. However, it can be useful to include a `published` port for local development, such as Docker.  
+:::
+
+### `command`
+(Optional)
+
+The command which will be run to start your service. If left out, the command from the Docker image will be used.  
+
+```yaml
+command: nginx -g 'daemon off;'
+```
+
+### `deploy`
+(Optional)
+
+The [Deploy Specification](https://github.com/compose-spec/compose-spec/blob/main/deploy.md) describes the runtime constraints and requirements for how your services will be deployed and managed across different environments (e.g. memory reservations, replicas, number of CPUs, etc.).
+
+```yaml
+deploy:
+  replicas: 1
+  reservations:
+    cpus: '0.5'
+    memory: 256M
+```
+
+### `depends_on`
+(Not yet supported)
+
+This property describes startup dependencies between services. This feature is currently unsupported by Defang, but can be useful in local developments such as Docker. 
+
+```yaml
+# depends_on: 
+#   - db
 ```
 
+### `environment`
+(Optional)
+
+The environment variables to set.
+```yaml
+environment:
+  DATABASE_USER: someuser
+```
 :::info
-Read more about configuration in the [Configuration page](./configuration.md).
+For sensitive environment variables (or secret values), you should list the variable's name with a blank or `null` value, and then securely set their actual value with `defang config` in the CLI. See our [Configuration page](/docs/concepts/configuration) for more.
+ 
+ For example:
+```yaml
+  - DATABASE_USER=someuser # env var loaded with this literal value
+  - DATABASE_PASSWORD # env var loaded using defang config
+```
 :::
+
+### `healthcheck`
+(Optional, but required for healthchecks on services with a published port)
+
+[This property](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#healthcheck) describes a check that will be run to determine whether or not a service's containers are "healthy". It works in the same way, and has the same default values, as the [HEALTHCHECK Dockerfile instruction](https://docs.docker.com/engine/reference/builder/#healthcheck) set by the service's Docker image. Your Compose file can override the values set in the Dockerfile.
+
+When using Defang, your Compose file must have a healthcheck if you want to expose an `ingress` port—even if your Dockerfile already contains one.
+
+:::note
+`curl` is commonly used for containers with an Ubuntu-based image, and `wget` is used for containers with an `alpine`-based image. 
+:::
+
+```yaml
+healthcheck:
+  test: ["CMD", "curl", "-f", "http://localhost:8080/"]
+  interval: 30s
+  timeout: 90s
+  retries: 3
+```
+
+or
+
+```yaml
+healthcheck:
+  test: ["CMD", "wget", "--spider", "http://localhost:8080/"]
+  interval: 30s
+  timeout: 90s
+  retries: 3
+```
+
+### `networks`
+(Optional)
+
+The network configuration. Can be `public`, where Defang will assign a public IP address, or `private`, in which Defang will not. To avoid warnings, add this to the [top-level `networks`](#networks) property as well. 
+
+```yaml
+networks:
+  public: 
+```
+
+You can also assign an alias for a network by using `aliases`, as seen below:
+```yaml
+networks:
+  public: 
+    aliases:
+      - app
+```
+ 
+See our [Networking](/docs/concepts/networking) page for more.
+ 
+### `restart`
+(Optional, but highly recommended)
+
+The restart mode for a container. Defaults to `unless-stopped` unless otherwise specified. 
+
+```yaml
+restart: unless-stopped
+```
+
+### `volumes`
+(Not yet supported)
+
+The volume mounts for a container, specific to a service. This feature is not currently supported by Defang.
+
+```yaml
+# volumes:
+#  - "./backend:/app"
+```

docs/concepts/configuration.md

@@ -19,6 +19,9 @@ defang config set API_KEY
 
 You can use sensitive config by specifying them in the `environment` section of a service in a `compose.yaml` file without any value, or by specifying an environment key with a `null` value in your Pulumi code.
 
+Either one of list notation or map notation is acceptable for defining your environment variable(s). See below for an example of each.
+
+#### With List Notation
 ```yaml
 services:
   service1:
@@ -27,9 +30,7 @@ services:
       - API_KEY
 ```
 
-You can also use this syntax:
-
-
+#### With Map Notation
 ```yaml
 services:
   service1:
@@ -45,7 +46,7 @@ You can find a sample of how to set sensitive config values [here](https://githu
 :::
 
 :::info
-Note that if you are using the [1-Click Deploy](/docs/tutorials/using-one-click-deploy) option, you can set sensitive config values as secrets in your GitHub repository and the action will automatically deploy them for you.
+If you are using the [1-Click Deploy](/docs/tutorials/using-one-click-deploy) option, you can set sensitive config values as secrets in your GitHub repository and the action will automatically deploy them for you. [Learn how to manage config values with the Defang Github Action](https://github.com/DefangLabs/defang-github-action?tab=readme-ov-file#managing-config-values).
 :::
 
 ## Interpolation

docs/concepts/domains.mdx

@@ -30,7 +30,7 @@ https://<username>-<service-name>--<port>.defang.dev
 If you're using [Defang BYOC](./defang-byoc.md), your domain will be:
 
 ```
-https://<service-name>--<port>.<username>.defang.app
+https://<service-name>--<port>.<project-name>.<username>.defang.app
 ```
   </TabItem>
 </Tabs>