Named Stacks: Deploy Multiple Environments from One Codebase

You've built your app. It works locally, but now you need to deploy it to production. You should probably set up a staging environment too. Oh, and your first enterprise customer wants their own isolated instance in their AWS account.

Suddenly you're managing four separate deployment pipelines, four sets of configs, and four potential points of failure.

This is the problem Stacks solves.

What is a Stack?

A Stack is an isolated deployment of your project. Same codebase, same compose file, completely separate infrastructure.

That's it. You now have a production environment running alongside your dev environment, with zero config duplication.

Each stack gets its own:

• ECS services
• Load balancers
• Databases (if you're using managed storage)
• DNS endpoints
• Environment variables
• Secrets

All from the same compose.yaml.

Why This Matters

Traditional infrastructure-as-code forces you to duplicate configurations for each environment. You end up with:

Three nearly-identical directories. Triple the maintenance. Triple the drift potential.

With Stacks, deploying to different environments is easy. Your infrastructure definition lives in your compose file, each environment is just a deployment target.

Real-World Use Cases

1. Dev / Staging / Production

The classic setup. Every team needs this, but setting it up traditionally takes days.

Each stack is completely isolated. Push a breaking change to dev? Staging and production don't care.

2. Multi-Tenant SaaS

You're selling to enterprises. They don't want shared infrastructure. They want their own instance, in their own cloud, with their own data isolation.

Each customer gets dedicated infrastructure. Their data never touches another customer's resources. Compliance teams love this.

3. Regional Deployments

Need to deploy closer to your users? Stacks can target different regions.

Same application, multiple geographic locations, managed from one codebase.

4. Feature Branch Previews

Want to preview a feature before merging? Spin up an ephemeral stack.

QA can test features in isolation. No more "it worked on my branch" arguments.

How It Works Under the Hood

When you create a stack, Defang creates a configuration file in .defang/[stack-name]:

Inside that file:

This file contains stack-specific settings that are loaded at deployment time. You should commit this file to your repo, so team members can share the same stack configurations. Secrets should never be stored in this file.

When you run defang up --stack=production, Defang:

1. Reads the stack configuration
2. Applies it to your compose.yaml
3. Provisions isolated infrastructure for that stack
4. Deploys your services

The key insight: your compose file is the source of truth. Stacks are just deployment targets.

Stack Commands Reference

Create a stack:

List all stacks:

Deploy to a stack:

View logs for a stack:

Tear down a stack:

Stack Configuration Options

Each stack can have different deployment modes:

Affordable Mode — Best for dev/staging. Uses Spot instances, skips NAT Gateway, minimizes cost.

Balanced Mode — The default. Good balance of cost and reliability.

High Availability Mode — For production. Multi-AZ deployment, maximum redundancy.

Configuring Secrets for Each Stack

Secrets are managed separately from stack configuration. Each stack can have its own secrets:

Your compose file references secrets normally:

Defang resolves the correct secret value based on which stack you're deploying to.

Best Practices

1. Commit Stack Files

Add .defang/ to your repo. Stack configurations should be version controlled so everyone on the team deploys consistently.

2. Use Affordable Mode unless deploying to Production

There's no reason to run Multi-AZ redundancy for a dev environment. Save money:

3. Name Stacks Descriptively

For customer deployments, use clear naming:

4. Use Stack List to Audit

Regularly check what's running:

Tear down unused stacks to avoid unnecessary costs.

From Zero to Multi-Environment in 5 Minutes

Here's a complete example. You have a compose.yaml:

Set up three environments:

Five minutes. Three fully isolated environments. Production-grade infrastructure.

No Terraform. No CloudFormation. No duplicated configs.

The Bottom Line

Stacks give you what every team needs but nobody wants to build: isolated, reproducible deployments from a single source of truth.

• One codebase — Your compose.yaml defines everything
• Infinite deployments — Spin up as many environments as you need
• Zero duplication — No more copy-pasting Terraform modules
• Per-stack configuration — Different modes, regions, and secrets for each deployment

Whether you're a solo developer who needs dev and prod, or an enterprise shipping to dozens of customers, Stacks scale with you.

Stacks are available in Defang CLI v2.4.0 and later. Get started here.