> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Quick Start

Get from zero to production in an hour.


**Prerequisites:**

- Node.js 22+
- Docker Desktop
- Terraform (for cloud deployment)

See [Prerequisites](/docs/getting-started/prerequisites) for detailed setup.


## Local Development

Make sure Docker Desktop is running, then:

```bash
# 1. Create your project (installs deps, builds libs, generates configs,
#    starts local infra, and creates the initial database migration)
npx @tsdevstack/cli init --template fullstack-auth

# 2. Enter the project
cd <your-project-name>

# 3. Start development
npm run dev
```

That's it. Your microservices are running locally with [Kong](https://konghq.com/) gateway, [PostgreSQL](https://www.postgresql.org/), and [Redis](https://redis.io/).

If Docker wasn't running during step 1, start it and run `npx tsdevstack sync` from the project directory before `npm run dev`.

### What you'll have

After running these commands, you get:

| Component       | URL                                                          | Description                                                                        |
| --------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| Gateway         | [http://localhost:8000](http://localhost:8000)               | Kong API gateway with routing and auth                                             |
| Swagger         | [http://localhost:\{port}/api](http://localhost:\{port}/api) | Per-service API docs (e.g., :3001/api)                                             |
| PostgreSQL      | localhost:5432                                               | Database with connection pooling                                                   |
| Redis           | localhost:6379                                               | Cache and session storage                                                          |
| pgAdmin         | [http://localhost:5050](http://localhost:5050)               | Database management UI ([admin@localhost.com](mailto:admin@localhost.com) / admin) |
| Redis Commander | [http://localhost:8081](http://localhost:8081)               | Redis browser and management UI                                                    |
| Prometheus      | [http://localhost:9090](http://localhost:9090)               | Metrics collection                                                                 |
| Grafana         | [http://localhost:4001](http://localhost:4001)               | Dashboards and visualization                                                       |
| Jaeger          | [http://localhost:16686](http://localhost:16686)             | Distributed tracing                                                                |

Each service you create gets:

- Hot reload on code changes
- Structured JSON logging
- Automatic health checks at `/health`
- Prometheus metrics at `/metrics`
- OpenAPI spec generation

As you develop, add more apps with `npx tsdevstack add-service` and run `npx tsdevstack sync` to update configs.

See [Running Locally](/docs/local-development/running-locally.md) for details.

## Deploy to Cloud

### 1. Create Cloud Account

Set up your cloud provider account and credentials. Choose one:

| Provider  | What to create                                   | Guide                                                                |
| --------- | ------------------------------------------------ | -------------------------------------------------------------------- |
| **GCP**   | Service account + JSON key                       | [GCP Setup](/docs/infrastructure/providers/gcp/account-setup.md)     |
| **AWS**   | IAM user + access key (separate account per env) | [AWS Setup](/docs/infrastructure/providers/aws/account-setup.md)     |
| **Azure** | App Registration + client secret                 | [Azure Setup](/docs/infrastructure/providers/azure/account-setup.md) |

### 2. Configure Credentials

Add your credentials to the provider-specific file in `.tsdevstack/`:

- GCP: `.credentials.gcp.json`
- AWS: `.credentials.aws.json`
- Azure: `.credentials.azure.json`

See the provider guide above for the exact format.

### 3. Initialize Cloud

```bash
npx tsdevstack cloud:init --gcp   # or --aws or --azure
```

This validates credentials, enables APIs, and grants required permissions automatically.

### 4. Initialize Infrastructure

```bash
npx tsdevstack infra:init --env dev
```

Creates the Terraform state backend and the infrastructure config schema for your provider.

### 5. Configure Domains

If you have frontend apps, add their domains to `.tsdevstack/infrastructure.json`:

```json
{
  "$schema": "./infrastructure.schema.json",
  "version": "1.0.0",
  "dev": {
    "frontend": {
      "domain": "example.com"
    }
  }
}
```

### 6. Deploy

```bash
npx tsdevstack infra:deploy --env dev
```

### 7. Configure DNS

The deploy command outputs:

- Load Balancer IP
- SSL validation records

Add these to your domain provider:

- A records pointing to the LB IP
- SSL validation CNAME records

See [Domain Setup](/docs/infrastructure/domain-setup.md) for details.

### 8. Wait for SSL

SSL certificates provision in 30-60 minutes. Then you're live.

## CI/CD

Automate deployments with GitHub Actions. You can deploy from local CLI, CI/CD, or both.

```bash
npx tsdevstack infra:init-ci --github
```

Then add environment-prefixed secrets to your repository (**Settings > Secrets and variables > Actions**). The secrets depend on your provider:

| Provider | Secrets per environment                                                                         |
| -------- | ----------------------------------------------------------------------------------------------- |
| GCP      | `GCP_WIF_DEV`, `GCP_SA_DEV`, `GCP_REGION_DEV`                                                   |
| AWS      | `AWS_ROLE_ARN_DEV`, `AWS_REGION_DEV`                                                            |
| Azure    | `AZURE_CLIENT_ID_DEV`, `AZURE_TENANT_ID_DEV`, `AZURE_SUBSCRIPTION_ID_DEV`, `AZURE_LOCATION_DEV` |

Replace `DEV` with `STAGING`, `PROD`, etc. for each environment.

If your project uses private npm packages, also add a single `NPM_TOKEN` repo secret (global, not per-env) and create an `.npmrc` at project root with `${NPM_TOKEN}` interpolation — tsdevstack auto-detects and threads it through generated workflows and docker builds. See [Private npm packages](/docs/infrastructure/cicd-setup.md#private-npm-packages).

See [CI/CD Setup](/docs/infrastructure/cicd-setup.md) and the provider-specific CI/CD pages for details.
