Getting started
What you'll have at the end of this page
- The offline probe passing locally, with no AWS account and no Docker.
- A real
dist/bootstrapanddist/lambda.zip, built from source on Amazon Linux 2023. - A live Lambda function deployed to your own AWS account, invoked once, and torn down again.
Prerequisites
| Tool | Why | Install |
|---|---|---|
| jolt | jolt probe runs the interpreted runtime loop locally, and jolt <task> reads this project's bb.edn directly, so it's the command every example on this page uses | brew install jolt-lang/jolt/jolt |
| babashka | jolt's task runner reads bb.edn, but several tasks (test, deploy, invoke, teardown, bench, the site:* tasks) shell out to a real bb binary internally, since they need clojure.test or cheshire, neither of which jolt bundles. You still need it installed even though you'll mostly type jolt, not bb | brew install borkdude/brew/babashka |
| Docker | Builds the deployable bootstrap binary on Amazon Linux 2023 (the glibc version has to match the real Lambda environment, see Building on Amazon Linux 2023) | docker.com |
| AWS CLI v2 | Every AWS-touching task shells out to it | brew install awscli |
| An AWS account | To deploy, invoke, and benchmark against | Credentials set up via AWS_PROFILE/AWS_REGION env vars or aws configure. Nothing in this repo hardcodes a profile, account, or region. |
Clone and probe
git clone git@github.com:b12n-oss/lambda-mvp-jlt.git
cd lambda-mvp-jlt
jolt probe
jolt probe runs the actual runtime loop (joltc run, interpreted, not the compiled bootstrap) against an offline mock of the Lambda Runtime API on an OS-assigned local port. No AWS account, no Docker, and it finishes in about two seconds. If this doesn't pass, nothing later in this page will either: it's the fastest signal that something about your joltc install or the runtime loop itself is wrong before you spend five minutes on a Docker build.
Run the unit suite the same way:
jolt test
Build the real binary
jolt image
This builds Chez Scheme and jolt from source inside an Amazon Linux 2023 container (the same OS Lambda's provided.al2023 execution environment runs), compiles the handler and runtime loop into one self-contained executable, and audits every non-glibc shared library it links. It takes several minutes the first time; Docker's own layer cache makes later builds faster. When it finishes, dist/bootstrap and dist/lambda.zip exist.
Deploy, invoke, tear down
jolt deploy
jolt invoke
jolt teardown
jolt deploy is idempotent: it creates the IAM role and Lambda function the first time, and updates them on every later call. jolt invoke runs a single ad-hoc invocation and prints the response body plus the CloudWatch REPORT line, the same line Cold vs. warm boot explains how to read. jolt teardown deletes both the function and the role, so nothing keeps running in your account.
Or all at once
jolt demo
jolt demo runs image, deploy and invoke in order. Before any of them it checks that docker and aws are on PATH, that the AWS CLI has credentials and a region (and prints the account it will deploy to), that your user can reach the Docker daemon, and that Docker can run containers for LAMBDA_ARCH. A missing piece stops it with the fix, before the build starts or anything changes in your account. Docker's layer cache makes repeat runs fast, so it's also the edit-and-redeploy loop for handler.clj.
Measure cold vs. warm boot time
jolt deploy
jolt bench
jolt teardown
jolt bench is the reason this project exists: it deploys at a few different memory tiers, measures one cold invocation and several warm ones at each, and prints a comparison table. See Cold vs. warm boot for what the numbers mean and how to reproduce a jolt-version comparison.
Next steps
Run jolt tasks to see every available command, including the documentation site tasks (jolt site:build/jolt site:serve). Architecture covers how the runtime loop, the build, and the bench tool fit together.