Skip to content

Commit 1ee8eb4

Browse files
rhedgpethrhedgpeth
committed
Initial additions
1 parent 1652d92 commit 1ee8eb4

13 files changed

+1596
-0
lines changed

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
node_modules/
2+
3+
.env

‎.gitmodules

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[submodule "src/client"]
2+
path = src/client
3+
url = https://github.com/mariadb-developers/todo-app-client.git

‎README.md

+230
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
# Places
2+
3+
**Places** is a web application backed by the power of the power, performance, and simplicity of [MariaDB](https://mariadb.com/), allows you to record all of your favorite locations using both structured (relational) and semi-structured (JSON) data!
4+
5+
<p align="center" spacing="10">
6+
<kbd>
7+
<img src="media/map.png" />
8+
</kbd>
9+
</p>
10+
11+
This application is made of two parts:
12+
13+
* Client
14+
- web UI that communicates with REST endpoints available through an API app (see below).
15+
- is a React.js project located in the [client](src/client) folder.
16+
* API
17+
- uses the [MariaDB Node.js Connector](https://github.com/mariadb-corporation/mariadb-connector-nodejs) to connect to MariaDB.
18+
- is a Node.js project located in the [api](src/api) folder.
19+
20+
This README will walk you through the steps for getting the `Places` web application up and running using MariaDB.
21+
22+
# Table of Contents
23+
1. [Requirements](#requirements)
24+
2. [Getting started with MariaDB and JSON](#mariadb)
25+
2. [Get the code](#code)
26+
4. [Configure, build and run the apps](#app)
27+
1. [Configure](#configure-api-app)
28+
2. [Create and activate a Python virtual environment](#activate-virtual-env)
29+
3. [Install Python packages](#install-python-packages)
30+
4. [Build and run the Python API app](#build-run-api)
31+
5. [Build and run the Client app](#build-run-client)
32+
5. [JSON Data Models](#data-models)
33+
6. [Support and contribution](#support-contribution)
34+
7. [License](#license)
35+
36+
## Requirements <a name="requirements"></a>
37+
38+
This sample application requires the following to be installed/enabled on your machine:
39+
40+
* [Node.js (v. 12+)](https://nodejs.org/docs/latest-v12.x/api/index.html) (for the Client/UI app)
41+
* [NPM (v. 6+)](https://docs.npmjs.com/) (for the Client/UI app)
42+
* [MariaDB command-line client](https://mariadb.com/products/skysql/docs/clients/mariadb-clients/mariadb-client/) (optional), used to connect to MariaDB database instances.
43+
44+
## 1.) Getting Started with MariaDB and JSON <a name="mariadb"></a>
45+
46+
Set up a MariaDB database, loaded with the data this sample needs, using the [MariaDB JSON Quickstart](https://github.com/mariadb-developers/mariadb-json-quickstart), before continuing to the next step.
47+
48+
## 2.) Get the code <a name="code"></a>
49+
50+
First, use [git](git-scm.org) (through CLI or a client) to retrieve the code using `git clone`:
51+
Ts
52+
```
53+
$ git clone https://github.com/mariadb-developers/places-app-nodejs.git
54+
```
55+
56+
Next, because this repo uses a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules), you will need to pull the [client application](https://github.com/mariadb-developers/todo-app-client) using:
57+
58+
```bash
59+
$ git submodule update --init --recursive
60+
```
61+
62+
## 3.) Configure, Build and Run the App <a name="app"></a>
63+
64+
This application is made of two parts:
65+
66+
* Client
67+
- web UI that communicates with REST endpoints available through an API app (see below).
68+
- is a React.js project located in the [client](src/client) folder.
69+
* API
70+
- uses the [MariaDB Node.js Connector](https://github.com/mariadb-corporation/mariadb-connector-nodejs) to connect to MariaDB.
71+
- is a Node.js project located in the [api](src/api) folder.
72+
73+
### a.) Configure the app <a name="configure-app"></a>
74+
75+
Configure the MariaDB connection by [adding an .env file to the Node.js project](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/master/documentation/promise-api.md#security-consideration). Add the .env file [here](src/api) (the `api` folder).
76+
77+
Example implementation:
78+
79+
```
80+
DB_HOST=<host_address>
81+
DB_PORT=<port_number>
82+
DB_USER=<username>
83+
DB_PASS=<password>
84+
DB_NAME=places
85+
```
86+
87+
**Configuring db.js**
88+
89+
The environmental variables from `.env` are used within the [db.js](src/api/db.js) for the MariaDB Node.js Connector configuration pool settings:
90+
91+
```javascript
92+
var mariadb = require('mariadb');
93+
require('dotenv').config();
94+
95+
const pool = mariadb.createPool({
96+
host: process.env.DB_HOST,
97+
user: process.env.DB_USER,
98+
password: process.env.DB_PASS,
99+
port: process.env.DB_PORT,
100+
database: process.env.DB_NAME,
101+
multipleStatements: true
102+
});
103+
```
104+
105+
**Configuring db.js for the MariaDB cloud database service [SkySQL](https://mariadb.com/products/skysql/)**
106+
107+
MariaDB SkySQL requires SSL additions to connection. It's as easy as 1-2-3 (steps below).
108+
109+
```javascript
110+
var mariadb = require('mariadb');
111+
require('dotenv').config();
112+
113+
// 1.) Access the Node File System package
114+
const fs = require("fs");
115+
116+
// 2.) Retrieve the Certificate Authority chain file (wherever you placed it - notice it's just in the Node project root here)
117+
const serverCert = [fs.readFileSync("skysql_chain.pem", "utf8")];
118+
119+
var pool = mariadb.createPool({
120+
host: process.env.DB_HOST,
121+
user: process.env.DB_USER,
122+
password: process.env.DB_PASS,
123+
port: process.env.DB_PORT,
124+
database: process.env.DB_NAME,
125+
connectionLimit: 5,
126+
// 3.) Add an "ssl" property to the connection pool configuration, using the serverCert const defined above
127+
ssl: {
128+
ca: serverCert
129+
}
130+
});
131+
```
132+
133+
### b.) Build and run the app <a name="build-run-api"></a>
134+
135+
To start and run the API application you need to execute the following commands within the [api root folder](src/api).
136+
137+
1. Install the Node.js packages (dependendies) for the app.
138+
139+
```bash
140+
$ npm install
141+
```
142+
143+
2. Run the the app, which will expose API endpoints via http://localhost:8080.
144+
145+
```bash
146+
$ npm start
147+
```
148+
149+
### c.) Build and run the [UI (Client) app](src/client) <a name="build-run-client"></a>
150+
151+
Once the API project is running you can now communicate with the exposed endpoints directly (via HTTP requests) or with the application UI, which is contained with the [client](src/client) folder of this repo.
152+
153+
To start the [client](src/client) application follow the instructions [here](https://github.com/mariadb-developers/places-app-client).
154+
155+
## JSON Data Models <a name="data-models"></a>
156+
157+
Below are samples of the data model per Location Type.
158+
159+
**Attraction (A)**
160+
```json
161+
{
162+
"category":"Landmark",
163+
"lastVisitDate":"11/5/2019"
164+
}
165+
```
166+
167+
**Restuarant (R)**
168+
```json
169+
{
170+
"details":{
171+
"foodType":"Pizza",
172+
"menu":"www.giodanos.com/menu"
173+
},
174+
"favorites":[
175+
{
176+
"description":"Classic Chicago",
177+
"price":24.99
178+
},
179+
{
180+
"description":"Salad",
181+
"price":9.99
182+
}
183+
]
184+
}
185+
```
186+
187+
**Sports Venue (S)**
188+
```json
189+
{
190+
"details":{
191+
"yearOpened":1994,
192+
"capacity":23500
193+
},
194+
"events":[
195+
{
196+
"date":"10/18/2019",
197+
"description":"Bulls vs Celtics"
198+
},
199+
{
200+
"date":"10/21/2019",
201+
"description":"Bulls vs Lakers"
202+
},
203+
{
204+
"date":"11/5/2019",
205+
"description":"Bulls vs Bucks"
206+
},
207+
{
208+
"date":"11/5/2019",
209+
"description":"Blackhawks vs Blues"
210+
}
211+
]
212+
}
213+
```
214+
215+
## Support and Contribution <a name="support-contribution"></a>
216+
217+
Please feel free to submit PR's, issues or requests to this project project directly.
218+
219+
If you have any other questions, comments, or looking for more information on MariaDB please check out:
220+
221+
* [MariaDB Developer Hub](https://mariadb.com/developers)
222+
* [MariaDB Community Slack](https://r.mariadb.com/join-community-slack)
223+
224+
Or reach out to us diretly via:
225+
226+
* [[email protected]](mailto:[email protected])
227+
* [MariaDB Twitter](https://twitter.com/mariadb)
228+
229+
## License <a name="license"></a>
230+
[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=plastic)](https://opensource.org/licenses/MIT)

‎media/map.png

443 KB
Loading

‎src/api/Dockerfile

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
2+
FROM node:8
3+
# Create app directory
4+
WORKDIR /usr/src/app
5+
# Install app dependencies
6+
COPY package*.json ./
7+
8+
RUN npm install
9+
# Copy app source code
10+
COPY . .
11+
12+
#Expose port and start application
13+
EXPOSE 80
14+
CMD [ "npm", "start" ]

‎src/api/README.md

+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Places - Node.js API
2+
3+
1. [Requirements](#requirements)
4+
2. [Getting started with the app](#getting-started)
5+
1. [Configure the code](#configure-code)
6+
2. [Build the code](#build-code)
7+
3. [Run the app](#run-app)
8+
9+
## Requirements <a name="requirements"></a>
10+
11+
This sample was created using the following techologies and they must be installed before proceeding.
12+
13+
* [Node.js (v. 12+)](https://nodejs.org/docs/latest-v12.x/api/index.html)
14+
* [NPM (v. 6+)](https://docs.npmjs.com/)
15+
16+
## Getting started with the app <a name="getting-started"></a>
17+
18+
### Configure the code <a name="configure-code"></a>
19+
20+
Configure the MariaDB connection by [adding an .env file to the Node.js project](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/master/documentation/promise-api.md#security-consideration).
21+
22+
Example implementation:
23+
24+
```
25+
DB_HOST=<host_address>
26+
DB_PORT=<port_number>
27+
DB_USER=<username>
28+
DB_PASS=<password>
29+
DB_NAME=<database>
30+
```
31+
32+
**Configuring db.js**
33+
34+
The environmental variables from `.env` are used within the [db.js](src/db.js) for the MariaDB Node.js Connector configuration pool settings:
35+
36+
```javascript
37+
var mariadb = require('mariadb');
38+
require('dotenv').config();
39+
40+
const pool = mariadb.createPool({
41+
host: process.env.DB_HOST,
42+
user: process.env.DB_USER,
43+
password: process.env.DB_PASS,
44+
port: process.env.DB_PORT,
45+
database: process.env.DB_NAME,
46+
multipleStatements: true,
47+
connectionLimit: 5
48+
});
49+
```
50+
51+
**Configuring db.js for the MariaDB cloud database service [SkySQL](https://mariadb.com/products/skysql/)**
52+
53+
MariaDB SkySQL requires SSL additions to connection. It's as easy as 1-2-3 (steps below).
54+
55+
```javascript
56+
var mariadb = require('mariadb');
57+
require('dotenv').config();
58+
59+
// 1.) Access the Node File System package
60+
const fs = require("fs");
61+
62+
// 2.) Retrieve the Certificate Authority chain file (wherever you placed it - notice it's just in the Node project root here)
63+
const serverCert = [fs.readFileSync("skysql_chain_t.pem", "utf8")];
64+
65+
var pools = [
66+
mariadb.createPool({
67+
host: process.env.DB_HOST,
68+
user: process.env.DB_USER,
69+
password: process.env.DB_PASS,
70+
port: process.env.DB_PORT,
71+
database: process.env.DB_NAME,
72+
multipleStatements: true,
73+
connectionLimit: 5,
74+
// 3.) Add an "ssl" property to the connection pool configuration, using the serverCert const defined above
75+
ssl: {
76+
ca: serverCert
77+
}
78+
})
79+
];
80+
```
81+
82+
### Build the code <a name="build-code"></a>
83+
84+
Once you have retrieved a copy of the code you're ready to build and run the project! However, before running the code it's important to point out that the application uses several Node Packages.
85+
86+
Executing the CLI command
87+
88+
```
89+
$ npm install
90+
```
91+
92+
Doing this targets relative `package.json` file and [install all dependencies](https://docs.npmjs.com/downloading-and-installing-packages-locally).
93+
94+
**IMPORTANT**: Be sure that the Node modules are installed for the [client](../../client). This can be done manually executing the following CLI command for [client](../../client):
95+
96+
```
97+
$ npm install
98+
```
99+
100+
### Run the app <a name="run-app"></a>
101+
102+
Once you've pulled down the code and have verified that all of the required Node packages are installed you're ready to run the application!
103+
104+
1. Execute the following CLI command
105+
106+
```bash
107+
$ npm start
108+
```
109+
110+
The following steps also exist within the ["Build and run"](../../#build-and-run-the-app-) section of the root README, and are for startin the React.js project once this API project has been started.
111+
112+
2. Navigate to the [../../client](client) folder and execute the following CLI command to start the React.js application.
113+
114+
```bash
115+
$ npm start
116+
```
117+
118+
3. Open a browser window and navigate to http://localhost:3000.

0 commit comments

Comments
 (0)