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.

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.

kanject new webapi --name Acme.Analytics --yes
cd Acme.Analytics

You get:

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

The default template ships with JWT auth and an xUnit test project. Drop either with --auth-provider none and --include-tests false.

2. Verify the toolchain

kanject doctor

If anything's red, fix it before continuing — deploy and test both depend on these checks passing.

3. Run it locally

kanject test

For a webapi template this calls dotnet run (or dotnet watch run with --watch) and routes the stage-resolved env vars in. For a Lambda template it shells into the Amazon.Lambda.TestTool with your project pre-loaded.

4. Inspect what got generated

A Kanject Program.cs is just an ASP.NET Core app with extension methods — no proprietary host, no magic. The same code runs locally under Kestrel and in production under Lambda:

using Kanject.Core.Adapter.Extensions;
using Kanject.Core.ApiV2.Extensions;
using Kanject.Core.NoSqlDatabase.Provider.DynamoDbV2.Extensions;

var builder = WebApplication.CreateBuilder(args);

// 1. Pull config from appsettings + AWS Parameter Store
builder.AddDefaultAppSettings();
builder.AddAwsSystemManagerParameterStore();

// 2. Register Kanject services via clean extension methods
builder.Services.AddDefaultAppServices();
builder.Services.AddDynamoNoSqlDatabase(options =>
{
    options.Namespace = appSettings.DatabaseNamespace;
    options.AwsRegion = appSettings.AwsRegion;
});

// 3. Lambda-ready by default — no separate host needed
builder.Services.AddAWSLambdaHosting(LambdaEventSource.HttpApi);

var app = builder.Build();

app.UseCoreExceptionHandlerMiddleware();
app.UseDefaultAppCors(builder.Configuration);
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

5. Configure the dev stage

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

{
  "schemaVersion": 1,
  "region": "eu-west-1",
  "profile": "default",
  "stack": "dev-acme-analytics",
  "artifactBucket": "dev-acme-analytics-artifacts",
  "parameterStore": {
    "path": "/acme-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:

kanject add secret JWT_SIGNING_KEY \
  acme-analytics/dev/jwt#key \
  --value "$(openssl rand -base64 32)" \
  --env dev

This creates / updates the secret, stores the value under JSON key key, and adds JWT_SIGNING_KEY = secret:acme-analytics/dev/jwt#key to your stage file. Verify what got recorded with kanject env --env dev (without leaking the value).

7. Deploy and rehearse rollback

# 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

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.