Skip to content

Commit 7a29ae5

Browse files
tebanieotebanieo
authored
Merge pull request #148 from tebanieo/master
Enhanced sample for the NERDS stack.
2 parents 8ee88f3 + 31dcf5c commit 7a29ae5

File tree

26 files changed

+1642
-0
lines changed

26 files changed

+1642
-0
lines changed

‎examples/NERDS/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,9 @@ To get started with the NERDS stack, navigate to the folders with the stack at d
2525
### 🎨 Basic Template
2626

2727
The [basic template](./basic-template/README.md) folder contains a basic template, which is a simple React-based application that will help you get started with working with DynamoDB. All the resources used in this lab are executed locally, so please make sure you have downloaded all the prerequisites before trying to run the sample applications.
28+
29+
### 🎨 Enhanced Template
30+
31+
The [enhanced template](./enhanced-template/README.md) folder contains an enhanced version of the basic template, which is a simple React-based application that will help you get started with working with DynamoDB. The table in this example uses a combination of Partition Key and a Sort Key that allows us to run more elegant queries in the backend and avoid to fetch unecessary data, this example showcase the use of [Query Operations](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html).
32+
33+
All the resources used in this lab are executed locally, so please make sure you have downloaded all the prerequisites before trying to run the sample applications.

‎examples/NERDS/enhanced-template/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Enhanced Template
2+
3+
In this example you will build the TaskMaster application!
4+
5+
![TaskMaster](./enhanced-backend/documentation/enhanced-app.png)
6+
7+
To execute this project please:
8+
9+
1. Open the [enhanced-backend](./enhanced-backend/README.md) folder with instructions to execute the backend locally.
10+
2. Open the [enhanced-frontend](./enhanced-frontend/README.md) folder with instructions to execute the front end and run your web applicaation locally.

‎examples/NERDS/enhanced-template/enhanced-backend/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 Esteban Serna
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎examples/NERDS/enhanced-template/enhanced-backend/README.md‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
# NERDS Stack - NodeJS Express React DynamoDB and SAM
2+
3+
## Enhanced example
4+
5+
This example includes additional DynamoDB functionality, you will work with a table with a Partition Key and a Sort Key that will allow you to run more elegant queries.
6+
7+
We will be working with an ehnahced task example where you will retrieve the tasks for a given user, and optional by priority.
8+
9+
This project contains source code and supporting files for a sample application running on Express and NodeJS with Amazon DynamoDB local. It includes the following files and folders:
10+
11+
![enhanced-recording](./documentation/enhanced-backend.gif)
12+
13+
## Folder Description
14+
15+
- `src` - Code for the express application and the APIs, and sample script to populate table.
16+
- `package.json` - Includes all the scripts to work on this project and the pre-requisites.
17+
18+
This application will create a couple of API methods to add and list the ToDos.
19+
20+
## Requirements
21+
22+
- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
23+
- [DynamoDB Local Docker Image](https://hub.docker.com/r/amazon/dynamodb-local)
24+
- [Node v22.3.0](https://nodejs.org/en/blog/release/v22.3.0)
25+
- [AWS JavaScript SDK v3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/)
26+
27+
## Usage
28+
29+
### DynamoDB local
30+
31+
This application will store all the information in an Amazon DynamoDB local instance, you will experience all the benefits from Amazon DynamoDB in your workstation.
32+
33+
Execute the command `npm run start-db`. If this is the first time running the command your output should look like the one below. Docker will obtain the latest version for you!
34+
35+
To start working with this project you need to first run `npm install`.
36+
37+
```bash
38+
❯ npm run start-db
39+
40+
> enhanced-backend@0.0.1 start-db
41+
> echo "CID=$(docker run -p $npm_package_config_ddbport:$npm_package_config_ddbport -d amazon/dynamodb-local -jar DynamoDBLocal.jar -sharedDb)" > .ddb_cid
42+
```
43+
44+
If you want to stop DynamoDB local execution you just need to run the command `npm run stop-db`. The long number at the end represents your docker container ID.
45+
46+
```shell
47+
❯ npm run stop-db
48+
49+
> enhanced-backend@0.0.1 stop-db
50+
> source .ddb_cid && docker stop $CID && rm .ddb_cid
51+
52+
904e9a494f0f09acd027e33d275d3a51a05716f09cc4eace87b778bc3e65e650
53+
```
54+
55+
### Working with DynamoDB tables
56+
57+
This project consists of a To-Do application and you will be storing all the items in a DynamoDB table. First you need to create a `recipes-table` table, where you will store all your to-dos.
58+
59+
Run the command command. `npm run create-recipes-table`
60+
61+
```bash
62+
❯ npm run create-recipes-table
63+
64+
> enhanced-backend@0.0.1 create-recipes-table
65+
> aws dynamodb create-table --table-name $npm_package_config_ddbEnhancedTable --attribute-definitions AttributeName=PK,AttributeType=S AttributeName=SK,AttributeType=S --key-schema AttributeName=PK,KeyType=HASH AttributeName=SK,KeyType=RANGE --billing-mode PAY_PER_REQUEST --endpoint-url http://${npm_package_config_ddbhost}:${npm_package_config_ddbport} --no-cli-page
66+
67+
{
68+
"TableDescription": {
69+
"AttributeDefinitions": [
70+
{
71+
"AttributeName": "PK",
72+
"AttributeType": "S"
73+
},
74+
{
75+
"AttributeName": "SK",
76+
"AttributeType": "S"
77+
}
78+
],
79+
"TableName": "social-recipes",
80+
"KeySchema": [
81+
{
82+
"AttributeName": "PK",
83+
"KeyType": "HASH"
84+
},
85+
{
86+
"AttributeName": "SK",
87+
"KeyType": "RANGE"
88+
}
89+
],
90+
"TableStatus": "ACTIVE",
91+
"CreationDateTime": "2024-09-25T13:38:11.310000-04:00",
92+
"ProvisionedThroughput": {
93+
"LastIncreaseDateTime": "1969-12-31T19:00:00-05:00",
94+
"LastDecreaseDateTime": "1969-12-31T19:00:00-05:00",
95+
"NumberOfDecreasesToday": 0,
96+
"ReadCapacityUnits": 0,
97+
"WriteCapacityUnits": 0
98+
},
99+
"TableSizeBytes": 0,
100+
"ItemCount": 0,
101+
"TableArn": "arn:aws:dynamodb:ddblocal:000000000000:table/social-recipes",
102+
"BillingModeSummary": {
103+
"BillingMode": "PAY_PER_REQUEST",
104+
"LastUpdateToPayPerRequestDateTime": "2024-09-25T13:38:11.310000-04:00"
105+
},
106+
"DeletionProtectionEnabled": false
107+
}
108+
}
109+
```
110+
111+
### List all the existing tables
112+
113+
To idenfity which tables you have created execute the command `npm run show-tables`.
114+
115+
```bash
116+
❯ npm run show-tables
117+
118+
> enhanced-backend@0.0.1 show-tables
119+
> aws dynamodb list-tables --endpoint-url http://$npm_package_config_ddbhost:$npm_package_config_ddbport --no-cli-page
120+
121+
{
122+
"TableNames": [
123+
"social-recipes"
124+
]
125+
}
126+
```
127+
128+
### Retrieve all the items from one table
129+
130+
List all the elements in the `social-recipes` table (Scan a table). `npm run scan-recipes`. However if your table is empty you will get this output.
131+
132+
```bash
133+
❯ npm run scan-recipes
134+
135+
> enhanced-backend@0.0.1 scan-recipes
136+
> aws dynamodb scan --table-name $npm_package_config_ddbEnhancedTable --endpoint-url http://$npm_package_config_ddbhost:$npm_package_config_ddbport --no-cli-page
137+
138+
{
139+
"Items": [],
140+
"Count": 0,
141+
"ScannedCount": 0,
142+
"ConsumedCapacity": null
143+
}
144+
```
145+
146+
### Populate sample data
147+
148+
Populate the `social-recipes` table with sample fake data:
149+
150+
```bash
151+
❯ npm run populate-recipe-table
152+
153+
> enhanced-backend@0.0.1 populate-recipe-table
154+
> node src/populate.js
155+
156+
Successfully inserted batch of 7 items
157+
All items have been processed
158+
```
159+
160+
Scan the table one more time `npm run scan-recipes`
161+
162+
```bash
163+
❯ npm run scan-recipes
164+
165+
> enhanced-backend@0.0.1 scan-recipes
166+
> aws dynamodb scan --table-name $npm_package_config_ddbEnhancedTable --endpoint-url http://$npm_package_config_ddbhost:$npm_package_config_ddbport --no-cli-page
167+
168+
{
169+
"Items": [
170+
{
171+
"taskDate": {
172+
"S": "2024-09-21T10:35:39"
173+
},
174+
"SK": {
175+
"S": "TASK#0#2024-09-21T10:35:39#hUkIVS7H3BKlEmQTNvNOe"
176+
},
177+
"taskPriority": {
178+
"S": "0"
179+
},
180+
"description": {
181+
"S": "Corvina is the best for a seviche"
182+
},
183+
"PK": {
184+
"S": "USER#4Rl17WTewD6aa1-k73cBJ"
185+
},
186+
"title": {
187+
"S": "Get some Corvina"
188+
},
189+
"userId": {
190+
"S": "4Rl17WTewD6aa1-k73cBJ"
191+
},
192+
"taskId": {
193+
"S": "hUkIVS7H3BKlEmQTNvNOe"
194+
}
195+
},
196+
...
197+
...
198+
{
199+
"SK": {
200+
"S": "USER#4Rl17WTewD6aa1-k73cBJ"
201+
},
202+
"Priorities": {
203+
"L": [
204+
{
205+
"N": "0"
206+
},
207+
{
208+
"N": "1"
209+
},
210+
{
211+
"N": "2"
212+
},
213+
{
214+
"N": "3"
215+
}
216+
]
217+
},
218+
"PK": {
219+
"S": "USER#4Rl17WTewD6aa1-k73cBJ"
220+
},
221+
"userId": {
222+
"S": "4Rl17WTewD6aa1-k73cBJ"
223+
},
224+
"Name": {
225+
"S": "John Doe"
226+
}
227+
}
228+
],
229+
"Count": 7,
230+
"ScannedCount": 7,
231+
"ConsumedCapacity": null
232+
}
233+
234+
```
235+
236+
### Initialize the backend
237+
238+
Finally to work with the sample express application, included in this project you will need to execute the instruction `npm run start-backend`, this process will start the express application that will be listening at port 3000.
239+
240+
Tip: execute this command in a new terminal
241+
242+
```shell
243+
❯ npm run start-backend
244+
245+
> enhanced-backend@0.0.1 start-backend
246+
> node src/server.js
247+
248+
Server is running on port 3000
249+
```
250+
251+
## Contributing
252+
253+
As soon as you clone this repository you need to run `pre-commit install` and before pushing any commit you need to run `detect-secrets scan > .secrets.baseline`. Failing to run this command will result in an invalid commit and it will be rejected.

‎examples/NERDS/enhanced-template/enhanced-backend/documentation/enhanced-app.png‎

63 KB
Loading

0 commit comments

Comments
 (0)