deploy

name	deploy
description	Deploy the current project to the cloud using Defang. Guides through CLI setup, authentication, compose file creation, stack selection, config management, and deployment.

Deploy the current project using the Defang CLI by following these steps:

Step 1: Validate the CLI

Run defang --version to confirm the CLI is installed. If it is not found, install it:

• npm: npm install -g @defang-io/defang
• Homebrew: brew install DefangLabs/defang/defang
• curl: eval "$(curl -fsSL s.defang.io/install)"

Step 2: Authenticate

Run defang whoami to check if the user is already logged in. If not, run defang login and wait for authentication to complete.

Step 3: Find or Create a compose.yaml file

Look for any compose.yaml files in the current directory or parent directories. If multiple are found, ask the user to select one. If none are found, ask the user if they want to create a new one. If yes, ask them about the services they want to deploy and generate a compose.yaml based on their answers. You will need to know which command each service should run, any environment variables they require, whether or not they should listen on a port, and if so, which one, and so on.

Step 4: Select or create a stack

A stack is a single deployed instance of the project in a specific cloud account and region, for example: production is deployed to aws in us-east-1. Additional configuration associated with a stack can be specified in the stack file (e.g., .defang/production). Note that stack variables are read at deployment time, and are not available at runtime in your application services.

List existing stacks:

defang stack list

• If one or more stacks exist, ask the user whether to use an existing one or create a new one.
• If no stacks exist, create a new one.

To create a stack interactively:

defang stack new

Required parameters:

• Name: alphanumeric, cannot start with a number (e.g., production)
• Provider: aws, gcp, or digitalocean
• Region: e.g., us-east-1 (AWS), us-central1 (GCP)
• Deployment Mode: controls cost and resiliency
  • affordable — lowest cost, for dev/test (default)
  • balanced — general production workloads
  • high_availability — critical services
  • See https://docs.defang.io/docs/concepts/deployment-modes

After creating a stack, set it as the default:

defang stack default STACK_NAME

Step 5: Set required configs

Check the compose.yaml for environment variables listed without a value — these must be set as configs before deployment.

List configs already set:

defang config ls

For each unset config, ask the user whether to provide a specific value or generate a random one. Do not assume a default. Then set it:

# specific value
defang config set KEY=value

# random value
defang config set --random KEY

# prompted securely (interactive)
defang config set KEY

Step 6: Deploy

defang compose up

Useful flags:

• -d / --detach: return immediately without streaming logs
• --force: force a fresh image build even if nothing changed
• --mode affordable|balanced|high_availability: override the stack's deployment mode

The CLI will stream logs automatically. If the deployment fails, Defang may offer an AI-assisted debug prompt — allow it to run before investigating manually.

Step 7: Verify

Once deployment completes, check service status and endpoints:

defang compose ps

To tail logs after the fact:

defang logs --follow
defang logs SERVICE_NAME --follow   # filter to one service