Places

Places is a web application backed by the power, performance, and simplicity of MariaDB, allows you to record all of your favorite locations using both structured (relational) and semi-structured (JSON) data!

This application is made of two parts:

Client
- web UI that communicates with REST endpoints available through an API app (see below).
- is a React.js project located in the client folder.
API
- uses the MariaDB Python Connector to connect to MariaDB.
- is a Python project located int the api folder.

This README will walk you through the steps for getting the Places web application up and running using MariaDB.

Requirements
Getting started with MariaDB and JSON
Get the code
Configure, build and run the apps
JSON Data Models
Support and contribution
License

Requirements

This sample application requires the following to be installed/enabled on your machine:

Python (v. 3+)
MariaDB Connector/C (v. 3.1.5+) (used by Connector/Python)
Node.js (v. 12+) (for the Client/UI app)
NPM (v. 6+) (for the Client/UI app)
MariaDB command-line client (optional), used to connect to MariaDB database instances.

1.) Getting Started with MariaDB and JSON

Set up a MariaDB database, loaded with the data this sample needs, using the MariaDB JSON Quickstart, before continuing to the next step.

2.) Get the code

First, use git (through CLI or a client) to retrieve the code using git clone: Ts

$ git clone https://github.com/mariadb-developers/places-app-python.git

Next, because this repo uses a git submodule, you will need to pull the client application using:

$ git submodule update --init --recursive

3.) Configure, Build and Run the App

This application is made of two parts:

Client
- web UI that communicates with REST endpoints available through an API app (see below).
- is a React.js project located in the client folder.
API
- uses the MariaDB Python Connector to connect to MariaDB.
- is a Python project located int the api folder.

a.) Configure the app

Configure the MariaDB connection by adding an .env file to the Node.js project. Add the .env file here (the api folder).

Example implementation:

DB_HOST=<host_address>
DB_PORT=<port_number>
DB_USER=<username>
DB_PASS=<password>
DB_NAME=places

Configuring db.js

The environmental variables from .env are used within src/api/tasks.py for the MariaDB Python Connector connection configuration settings:

config = {
    'host': os.getenv("DB_HOST"),
    'port': int(os.getenv("DB_PORT")),
    'user': os.getenv("DB_USER"),
    'password': os.getenv("DB_PASS"),
    'database': os.getenv("DB_NAME")
}

Note: MariaDB SkySQL requires SSL additions to connection. Details coming soon!

b.) Create and activate a Python virtual environment

A virtual environment is a directory tree which contains Python executable files and other files which indicate that it is a virtual environment. Basically, it's the backbone for running your Python Flask app.

Creation of virtual environments is done by executing the following command (within /src/api):

$ python3 -m venv venv

Tip: Tip: pyvenv is only available in Python 3.4 or later. For older versions please use the virtualenv tool.

Before you can start installing or using packages in your virtual environment, you’ll need to activate it. Activating a virtual environment will put the virtual environment-specific python and pip executables into your shell’s PATH.

Activate the virtual environment using the following command (within /src/api):

$ . venv/bin/activate activate

c.) Install Python packages

Flask is a micro web framework written in Python. It is classified as a microframework because it does not require particular tools or libraries.

TL;DR It's what this app uses for the API.

This app also uses the MariaDB Python Connector to connect to and communicate with MariaDB databases.

Install the necessary packages by executing the following command (within /src/api):

$ pip3 install flask mariadb python-dotenv

d.) Build and run the Python API app

Once you've pulled down the code and have verified that all of the required packages are installed you're ready to run the application!

From /src/api execute the following CLI command to start the the Python project, which will start the application on https://localhost:8080.

$ python3 api.py

e.) Build and run the UI (Client) app

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 folder of this repo.

To start the client application follow the instructions here.

JSON Data Models

Below are samples of the data model per Location Type.

Attraction (A)

{
   "category":"Landmark",
   "lastVisitDate":"11/5/2019"
}

Restuarant (R)

{
   "details":{
      "foodType":"Pizza",
      "menu":"www.giodanos.com/menu"
   },
   "favorites":[
      {
         "description":"Classic Chicago",
         "price":24.99
      },
      {
         "description":"Salad",
         "price":9.99
      }
   ]
}

Sports Venue (S)

{
   "details":{
      "yearOpened":1994,
      "capacity":23500
   },
   "events":[
      {
         "date":"10/18/2019",
         "description":"Bulls vs Celtics"
      },
      {
         "date":"10/21/2019",
         "description":"Bulls vs Lakers"
      },
      {
         "date":"11/5/2019",
         "description":"Bulls vs Bucks"
      },
      {
         "date":"11/5/2019",
         "description":"Blackhawks vs Blues"
      }
   ]
}

Support and Contribution

Please feel free to submit PR's, issues or requests to this project project directly.

If you have any other questions, comments, or looking for more information on MariaDB please check out:

Or reach out to us diretly via:

mariadb-developers/places-app-python