Added Serverless LocalStack example

examples.json

@@ -602,6 +602,23 @@
         "MariaDB Database",
         "MySQL Database"
       ]
+    },
+    {
+      "name": "Serverless LocalStack with S3 and DynamoDB",
+      "description": "Serverless Framework example to run lambda functions locally using [Serverless Offline](https://www.serverless.com/plugins/serverless-offline) with LocalStack. It provides a full local development environment using [Serverless LocalStack](https://www.serverless.com/plugins/serverless-localstack).",
+      "url": "https://github.com/nanlabs/devops-reference/tree/main/examples/serverless-localstack-with-s3-and-dynamodb/",
+      "tags": [
+        "Examples > DevOps > Infrastructure as Code > Serverless Framework, SAM and CloudFormation",
+        "Examples > DevOps > Containers, Orchestration and Serverless > Containers and Compositions (Docker, Docker Compose, Buildpacks and more)"
+      ],
+      "labels": [
+        "Serverless Framework",
+        "Serverless Offline",
+        "Serverless LocalStack",
+        "LocalStack",
+        "S3",
+        "DynamoDB"
+      ]
     }
   ]
 }

examples/serverless-localstack-with-s3-and-dynamodb/.env.example

@@ -0,0 +1,4 @@
+# Deployment Configuration
+SERVICE_NAME=serverless-localstack-example
+
+PROGRAMS_S3_BUCKET_NAME=serverless-localstack-bucket

examples/serverless-localstack-with-s3-and-dynamodb/.env.local

@@ -0,0 +1,4 @@
+# Deployment Configuration
+SERVICE_NAME=serverless-localstack-example
+
+PROGRAMS_S3_BUCKET_NAME=serverless-localstack-bucket

examples/serverless-localstack-with-s3-and-dynamodb/.eslintrc.js

@@ -0,0 +1,22 @@
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    project: './tsconfig.json',
+    tsconfigRootDir: __dirname,
+  },
+  plugins: ['@typescript-eslint/eslint-plugin'],
+  extends: ['plugin:@typescript-eslint/recommended', 'plugin:prettier/recommended'],
+  root: true,
+  env: {
+    node: true,
+    jest: true,
+  },
+  ignorePatterns: ['.eslintrc.js'],
+  rules: {
+    '@typescript-eslint/interface-name-prefix': 'off',
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-explicit-any': 'off',
+    '@typescript-eslint/no-empty-function': 'off',
+  },
+};

examples/serverless-localstack-with-s3-and-dynamodb/.eslitignore

@@ -0,0 +1,11 @@
+# /node_modules/* in the project root is ignored by default
+# build artefacts
+dist/*
+coverage/*
+node_modules/*
+logs/*
+prod/*
+.husky/*
+.github/*
+tools/
+localstack/volume

examples/serverless-localstack-with-s3-and-dynamodb/.gitignore

@@ -0,0 +1,46 @@
+# compiled output
+/dist
+/node_modules
+.tsbuildinfo
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# OS
+.DS_Store
+
+# Tests
+/coverage
+/.nyc_output
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# env
+.env
+.envrc
+
+# Serverless Framework
+.serverless
+.build
+.webpack
+.local-s3
+.volume

examples/serverless-localstack-with-s3-and-dynamodb/.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+pnpm run lint-staged

examples/serverless-localstack-with-s3-and-dynamodb/.husky/pre-push

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+pnpm run type-check

examples/serverless-localstack-with-s3-and-dynamodb/.lintstagedrc.json

@@ -0,0 +1,4 @@
+{
+  "*.{js,jsx,ts,tsx}": ["prettier --write", "npm run lint:fix"],
+  "*.{json,css,sass,scss,less,html,md,yml,yaml}": ["prettier --write"]
+}

examples/serverless-localstack-with-s3-and-dynamodb/.node-version

@@ -0,0 +1 @@
+v18.15.0

examples/serverless-localstack-with-s3-and-dynamodb/.prettierignore

@@ -0,0 +1,8 @@
+# /node_modules/* in the project root is ignored by default
+# build artefacts
+dist/*
+coverage/*
+node_modules/*
+logs/*
+prod/*
+localstack/volume

examples/serverless-localstack-with-s3-and-dynamodb/.prettierrc.js

@@ -0,0 +1,7 @@
+module.exports = {
+  semi: true,
+  trailingComma: 'all',
+  singleQuote: true,
+  printWidth: 120,
+  tabWidth: 2,
+};

examples/serverless-localstack-with-s3-and-dynamodb/README.md

@@ -0,0 +1,93 @@
+# Serverless LocalStack Example [![serverless](http://public.serverless.com/badges/v3.svg)](http://www.serverless.com)
+
+This project is a TypeScript based API generated using [create-awesome-node-app](https://www.npmjs.com/package/create-awesome-node-app). However, it is recommended to generate your own project using the command and following the options in the interactive menu. Please refer to the documentation for more information.
+
+We use Serverless Framework to do production ready deployments and local development using
+_serverless-offline_.
+
+## Features
+
+- 🦾 [TypeScript](https://www.typescriptlang.org/) - Ensures type safety
+- 🌐 API Gateway - Build scalable and maintainable APIs
+- ⚙️ Configuration Management - Manage different environments and configurations
+- 📜 Logging - Implement logging for debugging and monitoring purposes
+- 🧪 Unit Testing - Write and execute unit tests to ensure code quality
+
+## Pre-packed with
+
+- [TypeScript](https://www.typescriptlang.org/)
+- [ESLint](https://eslint.org/) - JavaScript and JSX linting utility
+- [Prettier](https://prettier.io/) - Opinionated code formatter
+- [Husky](https://www.npmjs.com/package/husky) - Simplifies Git hooks setup
+- [lint-staged](https://www.npmjs.com/package/lint-staged) - Runs linters against staged git files, preventing 💩 from slipping into your code base!
+
+## Requirements
+
+- [Docker](https://www.docker.com/)
+- [Docker Composer](https://docs.docker.com/compose/)
+- [Node.js](https://nodejs.org/en/) 18 or later
+
+  **You’ll need to have Node 18 or later on your local development machine** (but it’s not required on the server). You can use [fnm](https://github.com/Schniz/fnm) to easily switch Node versions between different projects.
+
+## Quickstart
+
+```sh
+# Setup NodeJs and install dependencies
+fnm use
+pnpm install
+
+# Run the Local Stack using Docker Compose
+docker-compose up -d
+
+# Run the application locally
+pnpm run sls:offline
+```
+
+## Testing locally
+
+```sh
+curl -X POST http://localhost:3000/program --header 'Content-Type': 'application/json' --data '{
+  "content": "console.log(\"Hello World\");",
+  "filePath": "example/file.js"
+}'
+```
+
+Then run the following command to check the uploaded file:
+
+```sh
+# Set the AWS credentials
+export AWS_ACCESS_KEY_ID="dummy-value"
+export AWS_SECRET_ACCESS_KEY="dummy-value"
+
+# List the uploaded files
+aws --endpoint-url=http://localhost:4566 --no-verify-ssl s3 ls --recursive serverless-localstack-bucket
+# 2023-10-31 18:00:00         18 example/file.js
+```
+
+## Development
+
+While developing, you will mostly rely on `pnpm run dev`; however, there are additional scripts available:
+
+| `pnpm run <script>` | Description                                                |
+| ------------------- | ---------------------------------------------------------- |
+| `sls:offline`       | Serves your app locally for development                    |
+| `format`            | Formats the project using [Prettier](https://prettier.io/) |
+| `lint`              | Lints the project for potential errors                     |
+| `lint:fix`          | Lints the project and fixes all correctable errors         |
+
+## Production
+
+Available scripts:
+
+| `pnpm run <script>` | Description                                            |
+| ------------------- | ------------------------------------------------------ |
+| `sls:package`       | Builds the application to the `.serverless/` directory |
+
+## Extra documentation
+
+You can find useful information such as project structure, available scripts and much more in the [docs](./docs) folder!
+
+## Recommended Resources
+
+We recommend checking out our awesome list of resources for learning about Serverless Framework, AWS Lambda,
+local development, and more. Check it out here: [Awesome NaN Labs](https://github.com/nanlabs/awesome-nan).

examples/serverless-localstack-with-s3-and-dynamodb/compose.yml

@@ -0,0 +1,45 @@
+version: '3.9'
+
+services:
+  localstack:
+    image: localstack/localstack:1.0.3
+    ports:
+      - '4566:4566' # LocalStack Gateway
+      - '4510-4559:4510-4559' # external services port range
+      # - "53:53" # DNS config (only required for Pro)
+      # - "53:53/udp" # DNS config (only required for Pro)
+      # - "443:443" # LocalStack HTTPS Gateway (only required for Pro)
+    environment:
+      - DEBUG=${DEBUG-}
+      - PERSISTENCE=${PERSISTENCE-}
+      - LAMBDA_EXECUTOR=${LAMBDA_EXECUTOR-}
+      # - LOCALSTACK_API_KEY=${LOCALSTACK_API_KEY-} # only required for Pro
+      - DOCKER_HOST=unix:///var/run/docker.sock
+      - SERVICES=dynamodb,s3,sqs
+    volumes:
+      - localstack-data:/var/lib/localstack'
+      - '/var/run/docker.sock:/var/run/docker.sock'
+    networks:
+      - localstack-net
+
+  setup-resources:
+    image: mesosphere/aws-cli:1.14.5
+    volumes:
+      - ./localstack:/project
+    environment:
+      - AWS_ACCESS_KEY_ID=dummyaccess
+      - AWS_SECRET_ACCESS_KEY=dummysecret
+      - AWS_DEFAULT_REGION=us-east-1
+    entrypoint: /bin/sh -c
+    command: /project/setup-resources.sh
+    networks:
+      - localstack-net
+    depends_on:
+      - localstack
+
+networks:
+  localstack-net:
+    driver: bridge
+
+volumes:
+  localstack-data:

examples/serverless-localstack-with-s3-and-dynamodb/docs/DEPLOYMENT.md

@@ -0,0 +1,25 @@
+# Serverless Deployment
+
+[![serverless](http://public.serverless.com/badges/v3.svg)](http://www.serverless.com)
+
+We use Serverless Framework to do production ready deployments.
+
+## Requirements
+
+**You’ll need to have Node 18 or later on your local development machine** (but it’s not required on the server). You can use [fnm](https://github.com/Schniz/fnm) to easily switch Node versions between different projects.
+
+```sh
+fnm use
+pnpm install
+```
+
+## AWS Lambda Deployment
+
+To deploy the app to AWS, you'll first need to configure your AWS credentials. There are many ways
+to set your credentials, for more information refer to the [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html).
+
+Once set you can deploy your app using the serverless framework with:
+
+```sh
+npm run sls:deploy
+```

examples/serverless-localstack-with-s3-and-dynamodb/docs/README.md

@@ -0,0 +1,8 @@
+# Extra Documentation
+
+This folder contains extra documentation for the project such us project structure, configuration, etc.
+
+## Resources
+
+- [Serverless Framework Documentation](https://www.serverless.com/)
+- [Deployment docs](./DEPLOYMENT.md)

examples/serverless-localstack-with-s3-and-dynamodb/jest.config.js

@@ -0,0 +1,11 @@
+module.exports = {
+  moduleFileExtensions: ['js', 'json', 'ts'],
+  rootDir: 'src',
+  testRegex: '.*\\.spec\\.ts$',
+  transform: {
+    '^.+\\.(t|j)s$': 'ts-jest',
+  },
+  collectCoverageFrom: ['**/*.(t|j)s'],
+  coverageDirectory: '../coverage',
+  testEnvironment: 'node',
+};

examples/serverless-localstack-with-s3-and-dynamodb/localstack/.gitignore

@@ -0,0 +1,2 @@
+.env
+volume/

examples/serverless-localstack-with-s3-and-dynamodb/localstack/README.md

@@ -0,0 +1,44 @@
+# LocalStack
+
+It will execute the script `setup-resources.sh` to setup the resources.
+
+## Resources
+
+Once the docker compose is up, it will create the following resources:
+
+- [DynamoDB Table](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html)
+- [S3 Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html)
+- [SQS Queue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html)
+
+## Testing
+
+From outside the container you can execute the following commands to test the service each service:
+
+- **DynamoDB**
+
+```sh
+$ aws --endpoint-url=http://localhost:4566 dynamodb list-tables
+{
+    "TableNames": [
+        "my_table"
+    ]
+}
+```
+
+- **S3**
+
+```sh
+$ aws --endpoint-url=http://localhost:4566 s3 ls
+2022-08-08 03:16:01 example-bucket
+```
+
+- **SQS**
+
+```sh
+$ aws --endpoint-url=http://localhost:4566 sqs list-queues
+{
+    "QueueUrls": [
+        "http://localhost:4566/000000000000/my_queue"
+    ]
+}
+```