diff --git a/README.md b/README.md index e6964ab..262f394 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,8 @@ # AWS Lambda [Rust](https://www.rust-lang.org/) docker builder πŸ‘ πŸ¦€ 🐳 [![Build Status](https://github.com/rust-serverless/lambda-rust/workflows/Main/badge.svg)](https://github.com/rust-serverless/lambda-rust/actions) - ## πŸ€” about -This docker image extends AWS Lambda `provided.al2 runtime environment, and installs [rustup](https://rustup.rs/) and the *stable* rust toolchain. +This docker image extends AWS Lambda `provided.al2` runtime environment, and installs [rustup](https://rustup.rs/) and the *stable* rust toolchain. This provides a build environment, consistent with your target execution environment for predictable results. @@ -24,7 +23,7 @@ The default docker entrypoint will build a packaged release optimized version of isolate the lambda specific build artifacts from your host-local build artifacts. > **⚠️ Note:** you can switch from the `release` profile to a custom profile like `dev` by providing a `PROFILE` environment variable set to the name of the desired profile. i.e. `-e PROFILE=dev` in your docker run - +> > **⚠️ Note:** you can include debug symbols in optimized release build binaries by setting `DEBUGINFO`. By default, debug symbols will be stripped from the release binary and set aside in a separate .debug file. You will want to volume mount `/code` to the directory containing your cargo project. @@ -40,15 +39,16 @@ A typical docker run might look like the following. ```sh $ docker run --rm \ - -u $(id -u):$(id -g) \ + -u "$(id -u)":"$(id -g)" \ -v ${PWD}:/code \ -v ${HOME}/.cargo/registry:/cargo/registry \ -v ${HOME}/.cargo/git:/cargo/git \ rustserverless/lambda-rust ``` + > πŸ’‘ The -v (volume mount) flags for `/cargo/{registry,git}` are optional but when supplied, provides a much faster turn around when doing iterative development -Note that `-u $(id -u):$(id -g)` argument is crucial for the container to produce artifacts +Note that `-u "$(id -u)":$(id -g)` argument is crucial for the container to produce artifacts owned by the current host user, otherwise you won't be able to `rm -rf target/lambda` or run `cargo update`, because the container will write artifacts owned by `root` docker user to `target/lambda` and `./cargo/{registry,git}` dirs which will break your dev and/or ci environment. @@ -86,8 +86,9 @@ $ docker run --rm \ ## βš“ using hooks -If you want to customize certain parts of the build process, you can leverage hooks that this image provides. -Hooks are just shell scripts that are invoked in a specific order, so you can customize the process as you wish. The following hooks exist: +You can leverage hooks provided in the image to customize certain parts of the build process. +Hooks are shell scripts that are invoked if they exist, so you can customize the process. The following hooks exist: + * `install`: run before `cargo build` - useful for installing native dependencies on the lambda environment * `build`: run after `cargo build`, but before packaging the executable into a zip - useful when modifying the executable after compilation * `package`: run after packaging the executable into a zip - useful for adding extra files into the zip file @@ -121,56 +122,33 @@ docker run \ -v ${HOME}/.cargo/git:/cargo/git \ rustserverless/lambda-rust -# start a one-off docker container replicating the "provided.al2" lambda runtime -# awaiting an event to be provided via stdin -$ docker run \ - -i -e DOCKER_LAMBDA_USE_STDIN=1 \ - --rm \ - -v ${PWD}/target/lambda/release/output/{your-binary-name}:/var/task:ro,delegated \ - public.ecr.aws/lambda/provided:al2 - -# provide an event payload via stdin (typically a json blob) +# Build a container with your binary as the runtime -# Ctrl-D to yield control back to your function -``` +$ docker build -t mylambda -f- . <