Update all docs before release

FieryCod · Nov 1, 2021 · 14bca45 · 14bca45
1 parent e6c4727
commit 14bca45
Show file tree

Hide file tree

Showing 18 changed files with 237 additions and 95 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,70 @@
 # Changelog
 
+## 0.6.2
+See [migration guide](https://fierycod.github.io/holy-lambda/#/migration-guide)
+
+- [bb tasks] Introduce `bb hl:update-bb-tasks` as an automation for updating to stable version of tasks.
+- [bb layer] Update babashka runtime to version `0.6.2`. Runtime does not precalculates the classpath. Cold start should be lower now! :) 
+- [bb layer] Use `bb.edn` for specifying dependencies for babashka code instead of relying on `deps.edn`.
+- [bb layer] Remove `babashka-shim` from the runtime, remove direct dependency on `holy-lambda`. 
+  Users should put the newest `holy-lambda` version in `bb.edn` and use `bb hl:babashka:sync` to download the dependencies.
+  Pack dependencies in the layer and reference it's ARN in `template.yml`.
+
+  **Example**
+  ```
+  AWSTemplateFormatVersion: '2010-09-09'
+  Transform: AWS::Serverless-2016-10-31
+  Description: >
+    Example basic lambda using `holy-lambda` micro library
+
+  Parameters:
+    Runtime:
+      Type: String
+      Default: provided
+    Timeout:
+      Type: Number
+      Default: 40
+    MemorySize:
+      Type: Number
+      Default: 128
+    HL_ENTRYPOINT:
+      Type: String
+      Default: com.company.example-lambda.core
+
+  Globals:
+    Function:
+      Runtime: !Ref Runtime
+      Timeout: !Ref Timeout
+      MemorySize: !Ref MemorySize
+      Environment:
+        Variables:
+          HL_ENTRYPOINT: !Ref HL_ENTRYPOINT
+
+  Resources:
+    BabashkaDepsLayer:
+      Type: AWS::Serverless::LayerVersion
+      Properties:
+        LayerName: BabashkaDepsLayer
+        ContentUri: ./.holy-lambda/bb-clj-deps
+
+    ExampleLambdaFunction:
+      Type: AWS::Serverless::Function
+      Properties:
+        FunctionName: ExampleLambdaFunction
+        Handler: com.company.example-lambda.core.ExampleLambda
+        CodeUri: src
+        Events:
+          HelloEvent:
+            Type: HttpApi
+            Properties:
+              ApiId: !Ref ServerlessHttpApi
+              Path: /
+              Method: GET
+        Layers:
+          - <HERE_PUT_PHISICAL_ID>
+          - !Ref BabashkaDepsLayer 
+   ...
+  ```
 ## 0.6.1
 - [bb layer] Update babashka to 0.6.3
 - [holy-lambda] Parse inner body to `:body-parsed` (see https://github.com/FieryCod/holy-lambda/issues/74)

diff --git a/README.md b/README.md
@@ -32,6 +32,9 @@ The extraordinary simple, performant, and extensible custom AWS Lambda runtime f
   - [nextdoc.io](https://nextdoc.io) - 6 native lambdas: api-gateway custom authorizer, file access control, openapi data source etc.
   - [scalably.ai](https://scalably.ai) - 14 native lambdas: xml transformations, sftp interactions, message routing, encryption etc.
   - [retailic](https://retailic.com/) - native lambda that uses compatibility layer with ring, regular Clojure api on ARM64 
+
+## Extensions
+  - [holy-lambda-ring-adapter](https://github.com/FieryCod/holy-lambda-ring-adapter) - Supports running full featured Ring apps on AWS Lambda
 
 ## Resources
 - [Documentation](https://fierycod.github.io/holy-lambda)

diff --git a/docs/babashka-backend-tutorial.md b/docs/babashka-backend-tutorial.md
@@ -51,7 +51,15 @@ This section will take you through the basics of Babashka backend.
 4. Copy the `Phisical ID` and put it in `template.yml`. Make sure to include `CodeUri` in the function properties and remove the global `CodeUri` set in `Parameters`.
 
     ```yml 
+    AWSTemplateFormatVersion: '2010-09-09'
+    Transform: AWS::Serverless-2016-10-31
+    Description: >
+      Example basic lambda using `holy-lambda` micro library
+
     Parameters:
+      Runtime:
+        Type: String
+        Default: provided
       Timeout:
         Type: Number
         Default: 40
@@ -64,18 +72,25 @@ This section will take you through the basics of Babashka backend.
 
     Globals:
       Function:
+        Runtime: !Ref Runtime
         Timeout: !Ref Timeout
         MemorySize: !Ref MemorySize
         Environment:
           Variables:
-          HL_ENTRYPOINT: !Ref HL_ENTRYPOINT
+            HL_ENTRYPOINT: !Ref HL_ENTRYPOINT
 
     Resources:
+      BabashkaDepsLayer:
+        Type: AWS::Serverless::LayerVersion
+        Properties:
+          LayerName: BabashkaDepsLayer
+          ContentUri: ./.holy-lambda/bb-clj-deps
+
       ExampleLambdaFunction:
         Type: AWS::Serverless::Function
         Properties:
-          Runtime: provided
           FunctionName: ExampleLambdaFunction
+          Handler: com.company.example-lambda.core.ExampleLambda
           CodeUri: src
           Events:
             HelloEvent:
@@ -86,8 +101,10 @@ This section will take you through the basics of Babashka backend.
                 Method: GET
           Layers:
             - <HERE_PUT_PHISICAL_ID>
-    ...
+            - !Ref BabashkaDepsLayer 
+       ...
     ```
+  4. Run `hl:babashka:sync` to download all necessary dependencies.
   5. Try to invoke the function using `AWS SAM CLI`
 
     ```bash

diff --git a/docs/cli.md b/docs/cli.md
@@ -19,13 +19,14 @@ CLI depends on the following programs:
 
   `bb <command-name> <args>`
 
-  | Command name       | Description                                                              |
-  |--------------------|--------------------------------------------------------------------------|
-  | `hl:compile`       | Compiles a project to `uberjar` via provided `:compile-cmd` in bb.edn    |
-  | `hl:doctor`        | Diagnoses common issues in the project.                                  |
-  | `hl:clean`         | Removes HL dependencies. Cleans `.holy-lambda` directory.                |
-  | `hl:version`       | Prints the current version of the tasks.                                 |
-  | `hl:docker:run`    | Runs a command specified as a string argument in the docker environment. |
+  | Command name         | Description                                                                      |
+  |----------------------|----------------------------------------------------------------------------------|
+  | `hl:compile`         | Compiles a project to `uberjar` via provided `:compile-cmd` in bb.edn            |
+  | `hl:doctor`          | Diagnoses common issues in the project.                                          |
+  | `hl:clean`           | Removes HL dependencies. Cleans `.holy-lambda` directory.                        |
+  | `hl:version`         | Prints the current version of the tasks.                                         |
+  | `hl:docker:run`      | Runs a command specified as a string argument in the docker environment.         |
+  | `hl:update-bb-tasks` | Automatically update the local version of tasks to latest stable remote version. |
 
 #### Backend specific tasks
 ##### Native
@@ -35,9 +36,9 @@ CLI depends on the following programs:
   | `hl:native:executable` | Provides native executable of the application, by using `native-image` under the hood. Generates `.holy-lambda/build/latest.zip`                                             |
 
 ## Babashka
-  | Command name       | Description                                                                                                                                                     |
-  |--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
-  | `hl:babashka:sync` | Downloads pods & Clojure dependencies to `.holy-lambda` folder. Both `.holy-lambda/bb-clj-deps` and `.holy-lambda/pods` should be packed to the separate layers |
+  | Command name       | Description                                                                                                                                                                                                                                                 |
+  |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+  | `hl:babashka:sync` | Downloads pods & Clojure dependencies to `.holy-lambda` folder. Dependencies are taken from `bb.edn :deps`, and `bb:edn :holy-lambda/options:backend:pods`. Both `.holy-lambda/bb-clj-deps` and `.holy-lambda/pods` should be packed to the separate layers |
 
 ## Possible options in `bb.edn` tasks
   - `:docker {:volumes, :network, :image}` - Docker execution environment configuration.

diff --git a/docs/examples/getting-started/babashka-backend/holy-lambda-example/bb.edn b/docs/examples/getting-started/babashka-backend/holy-lambda-example/bb.edn
@@ -1,49 +1,40 @@
 {:deps {io.github.FieryCod/holy-lambda-babashka-tasks
         {:git/url   "https://github.com/FieryCod/holy-lambda"
          :deps/root "./modules/holy-lambda-babashka-tasks"
-         :sha       "9e638fabae3506a3cbecefd375beda4774ae29fe"}}
+         :sha       "e6c47274a2bfc7576a9da0ccdbc079c1e83bee17"}
+        io.github.FieryCod/holy-lambda {:mvn/version "0.6.2"}}
 
  ;; Minimal babashka version which should be used in conjuction with holy-lambda
  :min-bb-version "0.3.7"
 
  :holy-lambda/options {
-                       ;; User should use docker for local development and use `HL_NO_DOCKER` environment variable
-                       ;; set to "true" for CI based deployments.
-                       ;; For CI based deployments user should base it's builder image on `fierycod/graalvm-native-image:ce`
                        :docker {
 
                                 ;; Check https://docs.docker.com/network/
                                 ;; Network setting for future versions of HL will propagate to AWS SAM as well
                                 ;; Options: "host"|"bridge"|"overlay"|"none"|nil|"macvlan"
                                 :network nil
 
-                                ;; HL runs bb tasks in docker context which means that local libraries will not work out-of-the-box.
-                                ;;
-                                ;; To make local libraries work with HL you have to:
-                                ;; 1. Mount your local library folder as a docker volume.
-                                ;; 2. Modify the `deps.edn` to use library path available in docker context.
-                                ;; Preferably use `deps.edn` alias and reference it's name in `:build:clj-name`
+                                ;; HL runs some bb tasks in docker context. You can put additional resources to the context by using volumes.
                                 ;; ----------------------------------------------------------------------------
                                 ;; Single volume definition:
                                 ;;
-                                ;; {:docker "/path-where-to-mount-local-library-on-docker"
-                                ;;  :host   "relative-local-library-path"}
+                                ;; {:docker "/where-to-mount-in-docker"
+                                ;;  :host   "relative-local-path"}
                                 :volumes []
 
                                 ;; GraalVM Community holy-lambda compatible docker image
                                 ;; You can always build your own GraalVM image with enterprise edition
                                 :image "ghcr.io/fierycod/holy-lambda-builder:amd64-java11-21.3.0"}
 
-                       :build {
-                               :compile-cmd  "clojure -X:uberjar"
+                       :build {:compile-cmd  "clojure -X:uberjar"
                                ;; Used when either :docker is nil or
                                ;; `HL_NO_DOCKER` environment variable is set to "true"
                                ;; Might be set via `GRAALVM_HOME` environment variable
                                :graalvm-home "~/.graalvm"}
 
                        :backend
                        {
-
                         ;; Babashka pods should be shipped using AWS Lambda Layer
                         ;; Check this template https://github.com/aws-samples/aws-lambda-layers-aws-sam-examples/blob/master/aws-sdk-layer/template.yaml
                         ;; and official docs https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-layers.html
@@ -53,23 +44,20 @@
                         ;; `IMPORTANT:` 3rd party babashka compatible libraries should be distributed as a layers (CodeUri: .holy-lambda/bb-clj-deps)
                         :pods {}
 
-                        ;; For `:native` runtime you can provide your own bootstrap file
+                        ;; For `:native` backend you can provide your own bootstrap file
                         :bootstrap-file "bootstrap"
 
-                        ;; For `:native` runtime you can provide some native resources which will be available during lambda execution
+                        ;; For `:native` backend you can provide some native resources which will be available during lambda execution
                         ;; Resources are packed as is.
                         :native-deps "resources"
 
                         ;; Specify custom arguments for native image generation
                         ;; Check https://www.graalvm.org/reference-manual/native-image/Options/
                         :native-image-args ["--verbose"
                                             "--no-fallback"
-                                            "--enable-url-protocols=http,https"
                                             "--report-unsupported-elements-at-runtime"
                                             "-H:+AllowIncompleteClasspath"
-                                            "--no-server"
-                                            "--initialize-at-build-time"]}}
-
+                                            "--no-server"]}}
 
  :tasks {:requires            ([holy-lambda.tasks])
          hl:docker:run        holy-lambda.tasks/hl:docker:run
@@ -79,4 +67,5 @@
          hl:compile           holy-lambda.tasks/hl:compile
          hl:doctor            holy-lambda.tasks/hl:doctor
          hl:clean             holy-lambda.tasks/hl:clean
+         hl:update-bb-tasks   holy-lambda.tasks/hl:update-bb-tasks
          hl:version           holy-lambda.tasks/hl:version}}
diff --git a/docs/examples/getting-started/babashka-backend/holy-lambda-example/deps.edn b/docs/examples/getting-started/babashka-backend/holy-lambda-example/deps.edn
@@ -1,5 +1,5 @@
 {:deps {org.clojure/clojure             {:mvn/version "1.10.3"}
-        io.github.FieryCod/holy-lambda  {:mvn/version "0.6.0"}}
+        io.github.FieryCod/holy-lambda  {:mvn/version "0.6.2"}}
 
  :paths                                 ["src" "resources"]
 

diff --git a/docs/examples/getting-started/babashka-backend/holy-lambda-example/template.yml b/docs/examples/getting-started/babashka-backend/holy-lambda-example/template.yml
@@ -13,7 +13,7 @@ Parameters:
   MemorySize:
     Type: Number
     Default: 128
-  Entrypoint:
+  HL_ENTRYPOINT:
     Type: String
     Default: com.company.example-lambda.core
 
@@ -24,9 +24,15 @@ Globals:
     MemorySize: !Ref MemorySize
     Environment:
       Variables:
-        Entrypoint: !Ref Entrypoint
+        HL_ENTRYPOINT: !Ref HL_ENTRYPOINT
 
 Resources:
+  BabashkaDepsLayer:
+    Type: AWS::Serverless::LayerVersion
+    Properties:
+      LayerName: BabashkaDepsLayer
+      ContentUri: ./.holy-lambda/bb-clj-deps
+
   ExampleLambdaFunction:
     Type: AWS::Serverless::Function
     Properties:
@@ -44,7 +50,8 @@ Resources:
             Path: /
             Method: GET
       Layers:
-        - arn:aws:lambda:eu-central-1:443526418261:layer:holy-lambda-babashka-runtime:47
+        - arn:aws:lambda:eu-central-1:443526418261:layer:holy-lambda-babashka-runtime-amd64:3
+        - !Ref BabashkaDepsLayer
     # For docker based deployments
     # Metadata:
     #   Dockerfile: Dockerfile