Skip to content

Commit 91c9e0c

Browse files
hernandosebastianhernandosebastian
authored
Update README.md
1 parent b048096 commit 91c9e0c

File tree

1 file changed

+122
-0
lines changed

1 file changed

+122
-0
lines changed

‎README.md

+122
Original file line numberDiff line numberDiff line change
@@ -1 +1,123 @@
11
![Coverage](https://img.shields.io/badge/coverage-84.25%25-brightgreen)
2+
3+
# Introduction
4+
This repository is an example of a basic CRUD application, designed to test and work locally with [API Gateway](https://aws.amazon.com/api-gateway/) and [Lambda](https://aws.amazon.com/lambda/). It utilizes [TypeScript](https://www.typescriptlang.org/) and [DynamoDB](https://aws.amazon.com/dynamodb/) as the database ([Dynamoose](https://dynamoosejs.com/getting_started/Introduction) as an optional ORM library).
5+
6+
All AWS services are run locally using [LocalStack](https://www.localstack.cloud/) within [Docker](https://www.docker.com/), allowing for a seamless development experience. Everything is containerized, enabling end-to-end local testing using [Jest](https://jestjs.io/) and [Supertest](https://www.npmjs.com/package/supertest) while seeding the database. All operations are run via scripts to simplify the process of packaging code for Lambda, along with its [dependencies as a layer](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html).
7+
8+
## LocalStack Services
9+
10+
This project utilizes the following LocalStack services:
11+
12+
- **API Gateway**: [LocalStack API Gateway Documentation](https://docs.localstack.cloud/user-guide/aws/apigateway/)
13+
- **Lambda**: [LocalStack Lambda Documentation](https://docs.localstack.cloud/user-guide/aws/lambda/)
14+
- **DynamoDB**: [LocalStack DynamoDB Documentation](https://docs.localstack.cloud/user-guide/aws/dynamodb/)
15+
16+
## Clarification
17+
18+
Everything has been tested on Windows; it has not been tested on Ubuntu or other operating systems. However, the libraries are cross-platform, so it shouldn't be too difficult to set everything up.
19+
20+
## Dependencies
21+
22+
- [**Docker**](https://www.docker.com/): To run the localstack Docker image.
23+
- [**7zip**](https://www.7-zip.org/): Installed and added to the PATH in environment variables to zip the code.
24+
- [**AWS CLI**](https://docs.aws.amazon.com/streams/latest/dev/setup-awscli.html): To run various localstack commands.
25+
- Ensure that the scripts run in the Windows console, as they may not execute properly in environments like VSCode.
26+
27+
## Run Locally
28+
29+
### Clone the project
30+
31+
```bash
32+
git clone https://github.com/Mipmipp/localstack-ts-api-gateway-lambda-dynamodb-crud-example.git
33+
```
34+
35+
### Go to the project directory
36+
37+
```bash
38+
cd localstack-ts-api-gateway-lambda-dynamodb-crud-example
39+
```
40+
41+
### Install dependencies
42+
43+
```bash
44+
npm ci
45+
```
46+
47+
### Start the server
48+
49+
```bash
50+
npm run start:dev
51+
```
52+
53+
## Environment Variables
54+
55+
To run this project, rename the `.env.dist` file to `.env` and populate it with the necessary environment variables.
56+
57+
## Running Tests
58+
59+
To run tests in the console:
60+
61+
```bash
62+
npm run test:dev
63+
```
64+
65+
## Package Scripts
66+
67+
| Command | Description |
68+
|----------------------------------------------|----------------------------------------------------------------------------------------------------------|
69+
| `test:e2e` | Runs end-to-end tests. |
70+
| `test:handler` | Runs unit tests against the handler index. |
71+
| `prebuild` | Deletes the `dist` folder. |
72+
| `create-package` | Creates an empty `package.json` in `temp-dependencies-layer`. |
73+
| `build:index` | Transpiles the `index.ts` code to JavaScript with a global handler banner in the output directory. |
74+
| `build:src` | Transpiles all TypeScript files excluding `index.ts`. |
75+
| `build:dependencies` | Edits a temp folder for non-development dependencies. |
76+
| `build` | Runs the commands to build the project. |
77+
| `postbuild` | Zips the contents of the temp folders to `dist` and deletes the temp folders. |
78+
| `start:local-db` | Runs scripts to start the local DynamoDB instance. |
79+
| `seed:local-db` | Runs scripts to seed the local database. |
80+
| `start:local-api` | Runs scripts to start the local API Gateway and Lambda. |
81+
| `wait-for-docker` | Runs scripts to wait for Docker to be ready. |
82+
| `start:dev` | Runs the complete setup for local development, including Docker and local database initialization. |
83+
| `test:dev` | Runs the complete setup for local testing, including Docker and end-to-end tests. |
84+
85+
## Bash Scripts
86+
87+
| Script Name | Description |
88+
|-----------------------------------------------|----------------------------------------------------------------------------------------------------------|
89+
| **`seed_local_dynamodb.sh`** | Seeds the local database with various items (can be omitted or edited). |
90+
| **`start_local_api_gateway_and_lambda.sh`** | Configures everything, deploying functions with the zipped handler code, creating Lambda functions, API Gateway, connecting endpoints, and generating a `.local.env` file with the endpoint and local API ID. This can be edited for various CRUD resources. |
91+
| **`start_local_dynamodb.sh`** | Creates an empty local database (can be updated to include tables and more). |
92+
| **`wait-for-docker.sh`** | Pings the Docker container endpoint to check if everything is up and running. |
93+
94+
## Local Endpoint
95+
96+
Once the scripts are executed, the `.local.env` file will contain the `LOCAL_API_ENDPOINT` variable, created by LocalStack. This changes with the `LOCAL_API_ID`, which is also stored for potential use in tests.
97+
98+
## Files for Lambda Deployment
99+
100+
In the `dist` directory, you will find:
101+
- **`index.zip`**: Minified JavaScript code from `src` ready for AWS Lambda deployment.
102+
- **`dependencies-layer.zip`**: Non-development dependencies packaged for Lambda as a layer.
103+
104+
## Database Suggestions
105+
106+
To manage and view your local DynamoDB database, we recommend using [**AWS NoSQL Workbench**](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.html). This tool provides a user-friendly interface for querying and visualizing data.
107+
108+
### Quick Setup Guide
109+
110+
1. **Install AWS NoSQL Workbench**: Download from the [AWS NoSQL Workbench website](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.settingup.html).
111+
112+
2. **Open the Application**: Launch NoSQL Workbench after installation.
113+
114+
3. **Add a Connection**:
115+
- Navigate to the **"Operation Builder"** tab.
116+
- Click **"Add connection"** and select **"DynamoDB Local"**.
117+
118+
4. **Configure Connection**:
119+
- Set the host to `localhost` and the port to `4566` (or your configured port).
120+
- Test the connection to ensure it's working.
121+
122+
5. **Start Managing Your Data**: Use the Operation Builder to run queries, insert items, and visualize your database.
123+

0 commit comments

Comments
 (0)