|
| 1 | +# Flights |
| 2 | + |
| 3 | +**Flights** is a web application, backed by the power of [MariaDB ColumnStore](https://mariadb.com/docs/features/mariadb-columnstore/), allows you to analyze millions [flight records from the United States Department of Transportation](https://www.transtats.bts.gov/DL_SelectFields.asp?Table_ID=236&DB_Short_Name=On-Time) in real time without needing to add any indexes! |
| 4 | + |
| 5 | +<p align="center" spacing="10"> |
| 6 | + <kbd> |
| 7 | + <img src="media/demo.gif" /> |
| 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 Python Connector](https://github.com/mariadb-corporation/mariadb-connector-python) to connect to MariaDB. |
| 18 | + - is a Python project located int the [api](src/api) folder. |
| 19 | + |
| 20 | +This README will walk you through the steps for getting the `Flights` web application up and running using MariaDB. |
| 21 | + |
| 22 | +# Table of Contents |
| 23 | +1. [Requirements](#requirements) |
| 24 | +2. [Getting started with MariaDB ColumnStore](#mariadb) |
| 25 | +3. [Get the code](#code) |
| 26 | +3. [Configure, build and run the app](#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 | +4. [Support and contribution](#support-contribution) |
| 33 | +5. [License](#license) |
| 34 | + |
| 35 | +## Requirements <a name="requirements"></a> |
| 36 | + |
| 37 | +This sample application requires the following to be installed/enabled on your machine: |
| 38 | + |
| 39 | +* [Python (v. 3+)](https://www.python.org/downloads/) |
| 40 | +* [MariaDB Connector/C (v. 3.1.5+)](https://mariadb.com/products/skysql/docs/clients/mariadb-connector-c-for-skysql-services/) (used by Connector/Python) |
| 41 | +* [Node.js (v. 12+)](https://nodejs.org/docs/latest-v12.x/api/index.html) (for the Client/UI app) |
| 42 | +* [NPM (v. 6+)](https://docs.npmjs.com/) (for the Client/UI app) |
| 43 | +* [MariaDB command-line client](https://mariadb.com/products/skysql/docs/clients/mariadb-clients/mariadb-client/) (optional), used to connect to MariaDB database instances. |
| 44 | + |
| 45 | +## 1.) Getting Started with MariaDB ColumnStore <a name="mariadb"></a> |
| 46 | + |
| 47 | +[MariaDB](https://mariadb.com) is a community-developed, commercially supported relational database management system, and the database you'll be using for this application. |
| 48 | + |
| 49 | +This sample uses MariaDB ColumnStore. The quickest way to get started is by using the [MariaDB ColumnStore Quickstart Guide](https://github.com/mariadb-developers/mariadb-columnstore-quickstart), which will walk you through the process of getting a MariaDB database instance (via Docker container) up, running and loaded with the data necessary for this sample app. |
| 50 | + |
| 51 | +**TL;DR** - Check out the [MariaDB ColumnStore Quickstart](https://github.com/mariadb-developers/mariadb-columnstore-quickstart) before proceeding to the next step. |
| 52 | + |
| 53 | +## 2.) Get the code <a name="code"></a> |
| 54 | + |
| 55 | +First, use [git](git-scm.org) (through CLI or a client) to retrieve the code using `git clone`: |
| 56 | + |
| 57 | +``` |
| 58 | +$ git clone https://github.com/mariadb-developers/flights-app-nodejs.git |
| 59 | +``` |
| 60 | + |
| 61 | +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: |
| 62 | + |
| 63 | +```bash |
| 64 | +$ git submodule update --init --recursive |
| 65 | +``` |
| 66 | + |
| 67 | +## Configure, Build and Run the App <a name="app"></a> |
| 68 | + |
| 69 | +**Important**: Before proceeding you'll need to have a MariaDB ColumnStore instance preloaded with flight data for this application to use. You can find more information [here](#mariadb). |
| 70 | + |
| 71 | +This application is made of two parts: |
| 72 | + |
| 73 | +* Client |
| 74 | + - web UI that communicates with REST endpoints available through an API app (see below). |
| 75 | + - is a React.js project located in the [client](src/client) folder. |
| 76 | +* API |
| 77 | + - uses the [MariaDB Node.js Connector](https://github.com/mariadb-corporation/mariadb-connector-nodejs) to connect to MariaDB. |
| 78 | + - is a Node.js project located in the [api](src/api) folder. |
| 79 | + |
| 80 | +### a.) Configure the app <a name="configure-api-app"></a> |
| 81 | + |
| 82 | +Configure the MariaDB connection by adding an [.env file](https://pypi.org/project/python-dotenv/) to the project within the [api](src/api) folder. |
| 83 | + |
| 84 | +Example implementation: |
| 85 | + |
| 86 | +``` |
| 87 | +DB_HOST=<host_address> |
| 88 | +DB_PORT=<port_number> |
| 89 | +DB_USER=<username> |
| 90 | +DB_PASS=<password> |
| 91 | +DB_NAME=travel |
| 92 | +``` |
| 93 | + |
| 94 | +**Configuring db.js** |
| 95 | + |
| 96 | +The environmental variables from `.env` are used within [src/api/tasks.py](src/api/tasks.py) for the MariaDB Python Connector connection configuration settings: |
| 97 | + |
| 98 | +```python |
| 99 | +config = { |
| 100 | + 'host': os.getenv("DB_HOST"), |
| 101 | + 'port': int(os.getenv("DB_PORT")), |
| 102 | + 'user': os.getenv("DB_USER"), |
| 103 | + 'password': os.getenv("DB_PASS"), |
| 104 | + 'database': os.getenv("DB_NAME") |
| 105 | +} |
| 106 | +``` |
| 107 | + |
| 108 | +**Configuring .env and tasks.py for the MariaDB cloud database service [SkySQL](https://mariadb.com/products/skysql/)** |
| 109 | + |
| 110 | +Note: MariaDB SkySQL requires SSL additions to connection. Details coming soon! |
| 111 | + |
| 112 | +### b.) Create and activate a Python virtual environment <a name="activate-virtual-env"></a> |
| 113 | + |
| 114 | +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. |
| 115 | + |
| 116 | +Creation of [virtual environments](https://docs.python.org/3/library/venv.html?ref=hackernoon.com#venv-def) is done by executing the following command (within [/src/api](src/api)): |
| 117 | + |
| 118 | +``` |
| 119 | +$ python3 -m venv venv |
| 120 | +``` |
| 121 | + |
| 122 | +**Tip**: Tip: pyvenv is only available in Python 3.4 or later. For older versions please use the [virtualenv](https://virtualenv.pypa.io/en/latest/) tool. |
| 123 | + |
| 124 | +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. |
| 125 | + |
| 126 | +Activate the virtual environment using the following command (within [/src/api](src/api)): |
| 127 | + |
| 128 | +```bash |
| 129 | +$ . venv/bin/activate activate |
| 130 | +``` |
| 131 | + |
| 132 | +### c.) Install Python packages <a name="install-python-packages"></a> |
| 133 | + |
| 134 | +[Flask](https://flask.palletsprojects.com/en/1.1.x/?ref=hackernoon.com) is a micro web framework written in Python. It is classified as a [microframework](https://en.wikipedia.org/wiki/Microframework) because it does not require particular tools or libraries. |
| 135 | + |
| 136 | +**TL;DR** It's what this app uses for the API. |
| 137 | + |
| 138 | +This app also uses the MariaDB Python Connector to connect to and communicate with MariaDB databases. |
| 139 | + |
| 140 | +Install the necessary packages by executing the following command (within [/src/api](src/api)): |
| 141 | + |
| 142 | +```bash |
| 143 | +$ pip3 install flask mariadb python-dotenv |
| 144 | +``` |
| 145 | + |
| 146 | +### d.) Build and run the [API app](src/api) <a name="build-run-api"></a> |
| 147 | + |
| 148 | +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! |
| 149 | + |
| 150 | +From [/src/api](src/api) execute the following CLI command to start the the Python project: |
| 151 | + |
| 152 | +```bash |
| 153 | +$ python3 api.py |
| 154 | +``` |
| 155 | +### e.) Build and run the [UI (Client) app](src/client) <a name="build-run-client"></a> |
| 156 | + |
| 157 | +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. |
| 158 | + |
| 159 | +To start and run the API application you need to execute the following commands within the [client root folder](src/client). |
| 160 | + |
| 161 | +1. Install the Node.js packages (dependendies) for the app. |
| 162 | + |
| 163 | +```bash |
| 164 | +$ npm install |
| 165 | +``` |
| 166 | + |
| 167 | +2. Run the the app, which will be available via a browser at http://localhost:3000. |
| 168 | + |
| 169 | +```bash |
| 170 | +$ npm start |
| 171 | +``` |
| 172 | + |
| 173 | +## Support and Contribution <a name="support-contribution"></a> |
| 174 | + |
| 175 | +Please feel free to submit PR's, issues or requests to this project project directly. |
| 176 | + |
| 177 | +If you have any other questions, comments, or looking for more information on MariaDB please check out: |
| 178 | + |
| 179 | +* [MariaDB Developer Hub](https://mariadb.com/developers) |
| 180 | +* [MariaDB Community Slack](https://r.mariadb.com/join-community-slack) |
| 181 | + |
| 182 | +Or reach out to us diretly via: |
| 183 | + |
| 184 | + |
| 185 | +* [MariaDB Twitter](https://twitter.com/mariadb) |
| 186 | + |
| 187 | +## License <a name="license"></a> |
| 188 | +[](https://opensource.org/licenses/MIT) |
| 189 | + |
0 commit comments