Merge remote-tracking branch 'origin/main' into postgres-docs

Author: raphaeltm

README.md

@@ -5,25 +5,31 @@ This website is built using [Docusaurus 2](https://docusaurus.io/), a modern sta
 ### Installation
 
 ```
-$ npm
+$ npm install
 ```
-
-### Local Development
+Make sure that you've cloned the `defanglabs/defang` repo and `defanglabs/samples` repo in sibling directories.
 
 ```
-$ npm serve
+$ git clone https://github.com/DefangLabs/defang.git ../defang 
+$ git clone https://github.com/DefangLabs/samples.git ../samples
 ```
 
-This command starts a local development server and opens up a browser window. 
-
 ### Build
 
 ```
-$ npm build
+$ npm run build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
+### Local Development
+
+```
+$ npm run start
+```
+
+This command starts a local development server and opens up a browser window. 
+
 ### Deployment
 
 Using SSH:

docs/concepts/compose.md

@@ -12,7 +12,7 @@ You might be familiar with `docker-compose.yml` files, now known as the [Compose
 
 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.
 
-When you run `defang up`, Defang will read your `compose.yaml` file and [deploy](./deployments.md) the services named in that file to the cloud.
+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
 
@@ -41,4 +41,4 @@ secrets:
 
 :::info Configuration & Secrets
 Read more about configuration in the [configuration page](./configuration.md) and about secrets in the [secrets page](./configuration.md).
-:::
+:::

docs/concepts/domains.mdx

@@ -75,15 +75,15 @@ You can also bring your own domain to a Defang project. This allows you to use y
 
 ### BYOC or Defang Playground
 
-If you are using [Defang BYOC](./defang-byoc.md) and *do not* have your domain's DNS hosted with your cloud provider, you will need to follow this flow:
+If you are using [Defang BYOC](./defang-byoc.md) and *do not* have your domain's DNS hosted with your cloud provider, or if you are using the [Defang Playground](./defang-playground.md), you will need to follow this flow:
 
 1. Add the `domainname` to your service definition.
 2. Run `defang compose up` to deploy your project.
 3. Run `defang cert generate` to generate an SSL certificate. This command will provide instructions for where to point your domain's DNS before the certificate can be issued.
 
 ### BYOC
 
-If you are using [Defang BYOC](./defang-byoc.md) and the DNS for your domain is hosted with your cloud provider (i.e. a Hosted Zone in Route 53, if you're using AWS), all you need to do is specify the `domainname` in your service definition, as in the example below.
+If you are using [Defang BYOC](./defang-byoc.md) *and the DNS for your domain is hosted with your cloud provider* (i.e. a Hosted Zone in Route 53, if you're using AWS), all you need to do is specify the `domainname` in your service definition, as in the example below.
 
 :::warning
 For the time being, you can only use one domain per service.

docs/concepts/observability.md

@@ -1,14 +1,14 @@
 ---
-title: Observability    
+title: Observability
 description: Monitor and debug your Defang services with the Defang CLI and portal.
 sidebar_position: 600
 ---
 
 # Observability
 
-You can easily monitor and debug your Defang services at build and runtime using the Defang CLI and portal. 
+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 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.
@@ -25,4 +25,4 @@ 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.
+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/faq.md

@@ -144,3 +144,31 @@ secrets:
 
 ### "Stack:… is in UPDATE_COMPLETE_CLEANUP_IN_PROGRESS state and cannot be updated"
 - This happens if different version of the Defang CLI are used with the same AWS account. Each version one will try to update the CD stack to its version, back and forth. Make sure that all users have the same version of the CLI. Check the CLI version using `defang version`.
+
+### "invalid healthcheck: ingress ports require an HTTP healthcheck on `localhost`.
+
+- This message is displayed when `defang compose up` tries to deploy a service with an "ingress" port, if the service does not have a `healthcheck` which mentions `localhost`. Defang routes a load balancer to your service's ingress ports, and the loadbalancer needs to be able to check the health of the service. To solve this issue, ask yourself these two questions:
+
+1. Should my service be public? It's common to declare your container's ports using the Compose file "shorthand" syntax (`1234:1234`). This syntax can be understood as `[HOST:]CONTAINER`. If your service is not intended to be public, you do not need to declare a HOST port. For example:
+
+    ```diff
+       services:
+         my-service:
+           image: my-image
+           ports:
+    -       - "1234:1234"
+    +       - "1234"
+    ```
+2. Does my healthcheck include the string `localhost`? It is very common to define a healthcheck by using `curl` or `wget` to make a request to `localhost`. So common, in fact, that defang will look for the string `localhost` in your healthcheck definition. For example, this healthcheck is valid:
+
+    ```yaml
+     healthcheck:
+       test: ["CMD", "curl", "-f", "http://localhost:1234/health"]
+    ```
+
+    This healthcheck is not valid for `ingress` ports:
+
+    ```yaml
+     healthcheck:
+       test: ["CMD", "./my-healthcheck"]
+    ```

docs/getting-started/getting-started.md

@@ -47,21 +47,21 @@ Defang supports various ways of creating and deploying services to the cloud. Th
 By default, all the output (stdout and stderr) from your app is logged. You can view these logs in real-time. You can view logs for all your services, one service, or even one specific deployment of a service.
 
 - From the CLI:
-    
+
     ```tsx
     defang tail --name service1
     ```
-    
+
 - From the Defang Portal:
-    
-    [https://portal.defang.dev/](https://portal.defang.dev/) 
+
+    [https://portal.defang.dev/](https://portal.defang.dev/)
 
 
 :::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 Playground.
 :::
-    
+
 
 ### Update Services
 
@@ -70,4 +70,3 @@ To update your app (for example, updating the base image of your container, or m
 :::info
 If you are using [compose files](../concepts/compose.md) to define your services, you can add/remove services, make changes to code, etc. When you run `defang compose up`, the update will be diffed against the current state and any necessary changes will be applied to make the current state match the desired state.
 :::
-

docs/getting-started/installing.md

@@ -3,40 +3,49 @@ sidebar_position: 100
 title: Installing
 description: How to install Defang.
 ---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
-# Installing
+# How to Install Defang
 
 Defang doesn't require installing anything in your cloud, but you will need to install the [open source](https://github.com/DefangLabs/defang) Defang command line interface (CLI) to interact with your Defang resources and account.
 
-We offer a few different ways to install the Defang CLI. You can use Homebrew, a bash script, Winget, or download the binary directly.
+We offer a few different ways to install the Defang CLI. You can use a bash script, Homebrew, Winget, or you can download the binary directly.
 
-## Using Homebrew
 
-You can easily install the Defang CLI using [Homebrew](https://brew.sh/). Run the following command in your terminal:
+<Tabs>
+  <TabItem value="bash" label="Bash">
+    ## Using a Bash Script
 
-```bash
-brew install DefangLabs/defang/defang
-```
+    You can install the Defang CLI using a bash script. Run the following command in your terminal:
 
-## Using a Bash Script
+    ```bash
+    . <(curl -Ls s.defang.io/install)
+    ```
 
-You can install the Defang CLI using a bash script. Run the following command in your terminal:
+    The script will try to download the appropriate binary for your operating system and architecture, add it to `~/.local/bin`, and add `~/.local/bin` to your `PATH` if it's not already there, with your permission. If you do not provide permission it will print an appropriate instruction for you to follow to add it manually. You can also customize the installation directory by setting the `INSTALL_DIR` environment variable before running the script.
+  </TabItem>
+  <TabItem value="homebrew" label="Homebrew" default>
+    ## Using Homebrew
 
-```bash
-. <(curl -Ls s.defang.io/install)
-```
+    You can easily install the Defang CLI using [Homebrew](https://brew.sh/). Run the following command in your terminal:
 
-The script will try to download the appropriate binary for your operating system and architecture, add it to `~/.local/bin`, and add `~/.local/bin` to your `PATH` if it's not already there, with your permission. If you do not provide permission it will print an appropriate instruction for you to follow to add it manually. You can also customize the installation directory by setting the `INSTALL_DIR` environment variable before running the script.
+    ```bash
+    brew install DefangLabs/defang/defang
+    ```
+  </TabItem>
+  <TabItem value="winget" label="Winget">
+    ## Using Winget
 
-## Using Winget
+    On Windows, you can install the Defang CLI using `winget`. Run the following command in your terminal:
 
-On Windows, you can install the Defang CLI using `winget`. Run the following command in your terminal:
-
-```powershell
-winget install defang
-```
-
-## Direct Download
-
-You can find the latest version of the Defang CLI on the [releases page](https://github.com/DefangLabs/defang/releases). Just download the appropriate binary for your operating system and architecture, and put it somewhere in your `PATH`.
+    ```powershell
+    winget install defang
+    ```
+  </TabItem>
+  <TabItem value="direct" label="Direct Download">
+    ## Direct Download
 
+    You can find the latest version of the Defang CLI on the [releases page](https://github.com/DefangLabs/defang/releases). Just download the appropriate binary for your operating system and architecture, and put it somewhere in your `PATH`.
+  </TabItem>
+</Tabs>

docusaurus.config.js

@@ -65,6 +65,7 @@ const config = {
       logo: {
         alt: 'Defang Logo',
         src: '/img/defang-logo.svg',
+        href: 'https://defang.io/',
       },
       items: [
         {