> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ubiquex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Your First Stack

> Build a real-world stack — RDS database wired to a Helm deployment.

This guide walks through building a real-world ubx stack: a PostgreSQL database whose endpoint flows automatically into a Helm chart deployment.

## What You'll Build

```
RDS PostgreSQL → endpoint → Helm chart (backend API)
                          → stack output (for other stacks)
```

## Prerequisites

* ubx installed — see [Installation](/v1/installation)
* AWS credentials configured — `ubx auth aws`
* kubectl + Helm installed

## 1. Create the Project

```bash theme={null}
ubx init my-platform
cd my-platform
```

## 2. Write the Stack

Replace `stack.iac` with:

```hcl theme={null}
input "env" {
  type    = "string"
  default = "staging"
}

input "db_password" {
  type      = "string"
  ephemeral = true
}

# PostgreSQL database
unit "aws_rds_instance" "db" {
  engine              = "postgres"
  engine_version      = "15"
  instance_class      = input.env == "prod" ? "db.r6g.xlarge" : "db.t3.micro"
  allocated_storage   = 20
  username            = "admin"
  password            = input.db_password
  skip_final_snapshot = true

  lifecycle {
    ignore_changes = ["password"]
  }
}

# Deploy backend — db endpoint wired in automatically
deploy "helm" "backend" {
  chart     = "my-backend"
  version   = "1.0.0"
  namespace = "backend"
  values = {
    database = {
      host = ~unit.aws_rds_instance.db.endpoint  # Pending<string>
      port = 5432
      name = "appdb"
    }
  }
}

# Export for other stacks
output "db_endpoint" {
  value       = ~unit.aws_rds_instance.db.endpoint
  description = "RDS connection endpoint"
}
```

## 3. Validate

```bash theme={null}
ubx validate
#   ◆ Compile    stack.iac
#   ✓  valid
```

## 4. Preview

```bash theme={null}
ubx plan
#   +  aws:rds:Instance         db         (new)
#   +  kubernetes:helm.sh/v3   backend    (new)
#
#   2 to create
```

## 5. Deploy

```bash theme={null}
pulumi config set db_password --secret "yourpassword"
ubx apply

#   +  aws:rds:Instance         db         45s
#   +  kubernetes:helm.sh/v3   backend     8s
#
#   ✓  done in 54s · 2 created
#
#   ─── Outputs ────────────────────────
#   db_endpoint  =  "db.xxxx.eu-west-1.rds.amazonaws.com"
```

The Helm chart received the RDS endpoint automatically — no manual copy-paste.

## 6. Add Environment Overrides

Create `envs/prod/overrides.iac`:

```hcl theme={null}
extend "unit" "aws_rds_instance" "db" {
  instance_class    = "db.r6g.2xlarge"
  allocated_storage = 100
  multi_az          = true
}
```

```bash theme={null}
ubx apply --env prod   # uses prod overrides
ubx apply              # uses staging defaults
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Multi-environment" icon="layers" href="/v1/guides/multi-environment">
    Staging vs production patterns
  </Card>

  <Card title="Secrets" icon="lock" href="/v1/guides/secrets">
    Secret management with secret()
  </Card>
</CardGroup>