Add docs for new stacks feature (#321)

* add stacks docs

* typo

* remove tabs from stacks doc

Co-authored-by: Copilot <[email protected]>

* Update docs/concepts/stacks.md

Co-authored-by: Jordan Stephens <[email protected]>

* Update docs/concepts/stacks.md

* Update docs/concepts/stacks.md

Co-authored-by: Jordan Stephens <[email protected]>

* Update docs/concepts/stacks.md

Co-authored-by: Jordan Stephens <[email protected]>

* Update docs/concepts/stacks.md

Co-authored-by: Jordan Stephens <[email protected]>

* Update docs/concepts/stacks.md

Co-authored-by: Copilot <[email protected]>

* Update docs/concepts/stacks.md

Co-authored-by: Jordan Stephens <[email protected]>

* Address unresolved review comments on stacks documentation (#328)

* Initial plan

* Address unresolved comments on stacks.md documentation

Co-authored-by: lionello <[email protected]>

* Apply suggestions from code review

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: lionello <[email protected]>
Co-authored-by: Lio李歐 <[email protected]>

---------

Co-authored-by: Jordan Stephens <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: lionello <[email protected]>

Author: 4 people

docs/concepts/services.md

@@ -1,14 +1,14 @@
 ---
 title: Services
-description: Defang allows you deploy services, defined as containers, to the cloud.
+description: Defang allows you to deploy services, defined as containers, to the cloud.
 ---
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
 # Services
 
-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 certain conventions for hostnames.
+Defang allows you to 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 certain conventions for hostnames.
 
 ### Service Name Resolution
 

docs/concepts/stacks.md

@@ -0,0 +1,70 @@
+---
+title: Stacks
+description: Defang supports deploying multiple instances of a project as separate stacks.
+---
+
+
+# Stacks
+
+Defang supports deploying multiple instances of a project as separate _stacks_. Each stack represents an isolated deployment of your project. Stacks allow you to manage different deployments of your project. For example, you can use stacks to support distinct development, staging, and production environments in the same cloud account. You can also use stacks to support deployments for different customers (e.g., Client A, Client B) or regions (e.g., North America, Europe) within the same project.
+
+:::info
+Stacks is a new feature introduced in Defang CLI v2.4.0 and is currently in preview. We welcome your feedback! Please open an issue on [GitHub](https://github.com/DefangLabs/defang/issues) if you encounter any problems or have suggestions.
+:::
+
+## Stack creation
+
+You can create a new stack using the Defang CLI:
+
+```bash
+defang stack new [stack-name]
+```
+
+This command initializes a new stack. If you don't specify a name, Defang will prompt you to enter one.
+
+After a stack is created, you will notice a new file in your working directory. If your stack was called `production`, you will see a file called `.defang/production`. Defang will never add secrets to this file. We recommend you add this file to your source code repository so you can share it with other contributors.
+
+## Stack deployment
+
+After a stack has been created, you can deploy it independently of others:
+
+```bash
+defang up --stack=<stack-name>
+```
+
+## Logging
+
+To view logs for a specific stack, use the following command:
+
+```bash
+defang logs --stack=<stack-name>
+```
+
+or to tail the logs in real-time:
+
+```bash
+defang tail --stack=<stack-name>
+```
+
+## Listing stacks
+
+This command shows all stacks in your project.
+
+```bash
+defang stack list
+
+NAME        PROVIDER  REGION     MODE
+production  aws       us-west-2  BALANCED  
+```
+
+## Internals
+
+When you create a new stack, Defang creates a new file for that stack in the `.defang` subfolder of your project directory. This file contains all the configuration and state information specific to that stack. Here's an example:
+
+```dotenv
+DEFANG_PROVIDER=aws
+AWS_REGION=us-west-2
+DEFANG_MODE=balanced
+```
+
+This file is very similar to `.env` files, but is specific to deployments of your project. This ensures that the values are not leaked into your runtime environment.