# Lambda quick start

A green-field service from `dotnet new` to `kanject aws deploy --env dev` in under 10 minutes. Assumes you've completed *Installation* and have an AWS account / profile configured.

**You'll learn**

- Scaffold a service with `kanject new` and run it locally with `kanject test`
- Read the generated Minimal API `Program.cs` — plain ASP.NET Core, Lambda-ready by default
- Configure a `dev` stage and bind a secret to an environment variable
- Deploy with `kanject aws deploy` and rehearse an alias-flip rollback

## 1. Scaffold the project

`kanject new` wraps `dotnet new`, installs the template pack if missing, and offers to run `kanject init` on every Lambda entry project it finds.

```bash
kanject new minimal-api --name Kanject.Analytics
cd Kanject.Analytics
```

You get:

```bash
Kanject.Analytics/
├── kanject-cli/
│   ├── manifest.json
│   ├── manifest.lock.json
│   └── stages/
│       ├── dev.json
│       ├── stage.json
│       └── prod.json
├── src/
│   └── Kanject.Analytics.Api/
│       ├── Kanject.Analytics.Api.csproj
│       ├── Program.cs
│       ├── appsettings.json
│       └── aws-lambda-tools-defaults.json
├── tests/
│   └── Kanject.Analytics.Api.Tests/
└── Kanject.Analytics.sln
```

The Minimal API starter keeps the application surface small and includes a wired xUnit test project. Use `webapi` instead when you want the controller-based structure from day one; pass `--include-tests false` only when you deliberately do not want tests.

> **Not sure where to begin?:** Run bare `kanject` for a short, project-aware landing screen. In an empty directory, bare `kanject new` lets you choose a template and then asks for the project name.

## 2. Run it locally

```bash
kanject test
```

For this Lambda-hosted Minimal API, `kanject test` launches the Amazon.Lambda.TestTool with the project pre-loaded. Add `--http` to run it as a normal local web host, or `--pull-env --env dev` only when you deliberately need live stage parameters and secrets in the process.

## 3. Verify the toolchain and stage

```bash
kanject doctor --env dev
```

Doctor checks the local toolchain and, with `--env dev`, the stage configuration and provider preflight. Fix red findings before deployment.

## 4. Inspect what got generated

The generated `Program.cs` is a real Minimal API: one host registration and normal `MapGet` endpoints. Lambda is a hosting detail, not an application framework. The template does not preselect a database or register optional Kanject Core services; add those only when the application needs them.

```csharp
using Amazon.Lambda.AspNetCoreServer;

var builder = WebApplication.CreateBuilder(args);

// Standard ASP.NET Core, hosted by Lambda in AWS.
builder.Services.AddAWSLambdaHosting(LambdaEventSource.RestApi);

var app = builder.Build();

app.MapGet("/health", () => Results.Ok(new
{
    status = "healthy",
    timestamp = DateTimeOffset.UtcNow
}));

app.Run();
```

## 5. Configure the dev stage

Open `kanject-cli/stages/dev.json` and fill in the AWS specifics. The bare minimum:

```json
{
  "schemaVersion": 2,
  "region": "eu-west-1",
  "profile": "default",
  "stack": "dev-kanject-analytics",
  "artifactBucket": "dev-kanject-analytics-artifacts",
  "parameterStore": {
    "path": "/kanject-analytics/dev/"
  },
  "env": {
    "ASPNETCORE_ENVIRONMENT": "Development"
  }
}
```

If the artifact bucket and Parameter Store path don't exist yet, the deploy fails with a clear AWS error — create them in the AWS console (or via your team's IaC) and try again.

## 6. Add a secret

Push a value to AWS Secrets Manager and bind it to an env var in one shot:

```bash
kanject add secret ANALYTICS_API_KEY \
  kanject-analytics/dev/api#key \
  --value "$(openssl rand -base64 32)" \
  --env dev
```

This creates or updates the secret, stores the value under JSON key `key`, and adds `ANALYTICS_API_KEY = secret:kanject-analytics/dev/api#key` to the stage file. Verify the binding with `kanject env --env dev` without fetching or leaking its remote value.

## 7. Deploy and rehearse rollback

```bash
# Deploy
kanject aws deploy --env dev

# Practise the rollback drill on a fresh deploy
kanject aws deployments list --env dev
kanject aws rollback --env dev --to previous-stable
```

`deploy` syncs deps, resolves every `param:` and `secret:` reference, regenerates the per-stage `aws-lambda-tools.dev.json`, calls `dotnet lambda deploy-serverless`, publishes a Lambda version, flips the alias, and writes a deployment-ledger entry to S3. Rollback flips the alias back — no rebuild.

> **What you get out of the box:** *Standard Minimal API endpoints* · *Lambda hosting without a separate application model* · *Stage-aware configuration* · *A wired test project* · *Local HTTP or Lambda TestTool execution*.

**Recap**

- `kanject new` wraps `dotnet new`, scaffolds the project, and offers to run `kanject init` on each Lambda entry project.
- `kanject test` launches the Lambda TestTool for this template; `--http` runs the same Minimal API as a normal local web host.
- Stage files under `kanject-cli/stages/` hold region, profile, stack, buckets, and the `env` map.
- `deploy` resolves every `param:` / `secret:` reference, flips the Lambda alias, and writes a ledger entry; `rollback` flips it back with no rebuild.

---
_Source: https://www.kanject.com/docs/quick-start/ · Kanject Docs_