Skip to content

Commit 84f89c9

Browse files
rhedgpethrhedgpeth
committed
Initial additions
1 parent 6cc3647 commit 84f89c9

File tree

8 files changed

+421
-0
lines changed

8 files changed

+421
-0
lines changed

‎.gitmodules

Lines changed: 3 additions & 0 deletions
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

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# TODO
2+
3+
**TODO** is a web application that introduces you to the power, performance, and simplicity of [MariaDB](https://mariadb.com/products/).
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+
- communicates with the API.
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 TODO web application up and running using MariaDB.
21+
22+
# Table of Contents
23+
1. [Requirements](#requirements)
24+
2. [Getting started with MariaDB](#mariadb)
25+
3. [Get the code](#code)
26+
4. [Create the database and table](#schema)
27+
5. [Configure, build and run the apps](#app)
28+
1. [Configure](#configure-api-app)
29+
2. [Create and activate a Python virtual environment](#activate-virtual-env)
30+
3. [Install Python packages](#install-python-packages)
31+
4. [Build and run the Python API app](#build-run-api)
32+
5. [Build and run the Client app](#build-run-client)
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+
* [Python (v. 3+)](https://www.python.org/downloads/)
41+
* [MariaDB Connector/C (v. 3.1.5+)](https://mariadb.com/products/skysql/docs/clients/mariadb-connector-c-for-skysql-services/) (used by Connector/Python)
42+
* [Node.js (v. 12+)](https://nodejs.org/docs/latest-v12.x/api/index.html) (for the Client/UI app)
43+
* [NPM (v. 6+)](https://docs.npmjs.com/) (for the Client/UI app)
44+
* [MariaDB command-line client](https://mariadb.com/products/skysql/docs/clients/mariadb-clients/mariadb-client/) (optional), used to connect to MariaDB database instances.
45+
46+
## 1.) Getting Started with MariaDB <a name="mariadb"></a>
47+
48+
[MariaDB](https://mariadb.com) is a community-developed, commercially supported relational database management system, and the database you'll be using for this application.
49+
50+
If you don't have a MariaDB database up and running you can find more information on how to download, install and start using a MariaDB database in the [MariaDB Quickstart Guide](https://github.com/mariadb-developers/mariadb-getting-started).
51+
52+
## 2.) Get the code <a name="code"></a>
53+
54+
First, use [git](git-scm.org) (through CLI or a client) to retrieve the code using `git clone`:
55+
56+
```
57+
$ git clone https://github.com/mariadb-developers/todo-app-python.git
58+
```
59+
60+
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:
61+
62+
```bash
63+
$ git submodule update --init --recursive
64+
```
65+
66+
## 3.) Create the database and table <a name="schema"></a>
67+
68+
[Connect to your MariaDB database](https://mariadb.com/products/skysql/docs/clients/) (from [Step #2](#mariadb)) and execute the following SQL scripts using the following options:
69+
70+
a.) Use the [MariaDB command-line client](https://mariadb.com/products/skysql/docs/clients/mariadb-clients/mariadb-client/) to execute the SQL contained within [schema.sql](schema.sql).
71+
72+
_Example command:_
73+
```bash
74+
$ mariadb --host HOST_ADDRESS --port PORT_NO --user USER --password PASSWORD < schema.sql
75+
```
76+
77+
**OR**
78+
79+
b.) Copy, paste and execute the raw SQL commands contained in [schema.sql](schema.sql) using a [client of your choice](https://mariadb.com/products/skysql/docs/clients/).
80+
81+
```sql
82+
CREATE DATABASE todo;
83+
84+
CREATE TABLE todo.tasks (
85+
id INT(11) unsigned NOT NULL AUTO_INCREMENT,
86+
description VARCHAR(500) NOT NULL,
87+
completed BOOLEAN NOT NULL DEFAULT 0,
88+
PRIMARY KEY (id)
89+
);
90+
```
91+
92+
## 4.) Configure, Build and Run the App <a name="app"></a>
93+
94+
This application is made of two parts:
95+
96+
* Client
97+
- communicates with the API.
98+
- is a React.js project located in the [client](src/client) (/src/client) folder.
99+
* API
100+
- uses the [MariaDB Python Connector](https://github.com/mariadb-corporation/mariadb-connector-python) to connect to MariaDB.
101+
- is a Python project located int the [api](src/api) (/src/api) folder.
102+
103+
The following steps, `a` through `e`, will walk you through the process of configuring, building and running the `api` and `client` applications.
104+
105+
### a.) Configure the app <a name="configure-api-app"></a>
106+
107+
Configure the MariaDB connection by adding an [.env file](https://pypi.org/project/python-dotenv/) to the project within the [api](src/api) folder.
108+
109+
Example implementation:
110+
111+
```
112+
DB_HOST=<host_address>
113+
DB_PORT=<port_number>
114+
DB_USER=<username>
115+
DB_PASS=<password>
116+
DB_NAME=todo
117+
```
118+
119+
**Configuring db.js**
120+
121+
The environmental variables from `.env` are used within [src/api/tasks.py](src/api/tasks.py) for the MariaDB Python Connector connection configuration settings:
122+
123+
```python
124+
config = {
125+
'host': os.getenv("DB_HOST"),
126+
'port': int(os.getenv("DB_PORT")),
127+
'user': os.getenv("DB_USER"),
128+
'password': os.getenv("DB_PASS"),
129+
'database': os.getenv("DB_NAME")
130+
}
131+
```
132+
133+
**Configuring .env and tasks.py for the MariaDB cloud database service [SkySQL](https://mariadb.com/products/skysql/)**
134+
135+
Note: MariaDB SkySQL requires SSL additions to connection. Details coming soon!
136+
137+
### b.) Create and activate a Python virtual environment <a name="activate-virtual-env"></a>
138+
139+
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.
140+
141+
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)):
142+
143+
```
144+
$ python3 -m venv venv
145+
```
146+
147+
**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.
148+
149+
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.
150+
151+
Activate the virtual environment using the following command (within [/src/api](src/api)):
152+
153+
```bash
154+
$ . venv/bin/activate activate
155+
```
156+
157+
### c.) Install Python packages <a name="install-python-packages"></a>
158+
159+
[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.
160+
161+
**TL;DR** It's what this app uses for the API.
162+
163+
This app also uses the MariaDB Python Connector to connect to and communicate with MariaDB databases.
164+
165+
Install the necessary packages by executing the following command (within [/src/api](src/api)):
166+
167+
```bash
168+
$ pip3 install flask mariadb python-dotenv
169+
```
170+
171+
### d.) Build and run the [API app](src/api) <a name="build-run-api"></a>
172+
173+
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!
174+
175+
From [/src/api](src/api) execute the following CLI command to start the the Python project:
176+
177+
```bash
178+
$ python3 api.py
179+
```
180+
181+
**Note:** You will need to use seperate terminals for the `client` and `api` apps.
182+
183+
### e.) Build and run the [UI (Client) app](src/client) <a name="build-run-client"></a>
184+
185+
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.
186+
187+
To start the [client](src/client) application follow the instructions [here](https://github.com/mariadb-developers/todo-app-client).
188+
189+
## Support and Contribution <a name="support-contribution"></a>
190+
191+
Please feel free to submit PR's, issues or requests to this project project directly.
192+
193+
If you have any other questions, comments, or looking for more information on MariaDB please check out:
194+
195+
* [MariaDB Developer Hub](https://mariadb.com/developers)
196+
* [MariaDB Community Slack](https://r.mariadb.com/join-community-slack)
197+
198+
Or reach out to us diretly via:
199+
200+
* [[email protected]](mailto:[email protected])
201+
* [MariaDB Twitter](https://twitter.com/mariadb)
202+
203+
## License <a name="license"></a>
204+
[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=plastic)](https://opensource.org/licenses/MIT)

‎media/demo.gif

233 KB
Loading

‎schema.sql

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
CREATE DATABASE todo;
2+
3+
CREATE TABLE todo.tasks (
4+
id INT(11) unsigned NOT NULL AUTO_INCREMENT,
5+
description VARCHAR(500) NOT NULL,
6+
completed BOOLEAN NOT NULL DEFAULT 0,
7+
PRIMARY KEY (id)
8+
);

‎src/api/.gitignore

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Distribution / packaging
10+
.Python
11+
build/
12+
develop-eggs/
13+
dist/
14+
downloads/
15+
eggs/
16+
.eggs/
17+
lib/
18+
lib64/
19+
parts/
20+
sdist/
21+
var/
22+
wheels/
23+
share/python-wheels/
24+
*.egg-info/
25+
.installed.cfg
26+
*.egg
27+
MANIFEST
28+
29+
# PyInstaller
30+
# Usually these files are written by a python script from a template
31+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
32+
*.manifest
33+
*.spec
34+
35+
# Installer logs
36+
pip-log.txt
37+
pip-delete-this-directory.txt
38+
39+
# Unit test / coverage reports
40+
htmlcov/
41+
.tox/
42+
.nox/
43+
.coverage
44+
.coverage.*
45+
.cache
46+
nosetests.xml
47+
coverage.xml
48+
*.cover
49+
*.py,cover
50+
.hypothesis/
51+
.pytest_cache/
52+
cover/
53+
54+
# Translations
55+
*.mo
56+
*.pot
57+
58+
# Django stuff:
59+
*.log
60+
local_settings.py
61+
db.sqlite3
62+
db.sqlite3-journal
63+
64+
# Flask stuff:
65+
instance/
66+
.webassets-cache
67+
68+
# Scrapy stuff:
69+
.scrapy
70+
71+
# Sphinx documentation
72+
docs/_build/
73+
74+
# PyBuilder
75+
.pybuilder/
76+
target/
77+
78+
# Jupyter Notebook
79+
.ipynb_checkpoints
80+
81+
# IPython
82+
profile_default/
83+
ipython_config.py
84+
85+
# pyenv
86+
# For a library or package, you might want to ignore these files since the code is
87+
# intended to run in multiple environments; otherwise, check them in:
88+
# .python-version
89+
90+
# pipenv
91+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
93+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
94+
# install all needed dependencies.
95+
#Pipfile.lock
96+
97+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow
98+
__pypackages__/
99+
100+
# Celery stuff
101+
celerybeat-schedule
102+
celerybeat.pid
103+
104+
# SageMath parsed files
105+
*.sage.py
106+
107+
# Environments
108+
.env
109+
.venv
110+
env/
111+
venv/
112+
ENV/
113+
env.bak/
114+
venv.bak/
115+
116+
# Spyder project settings
117+
.spyderproject
118+
.spyproject
119+
120+
# Rope project settings
121+
.ropeproject
122+
123+
# mkdocs documentation
124+
/site
125+
126+
# mypy
127+
.mypy_cache/
128+
.dmypy.json
129+
dmypy.json
130+
131+
# Pyre type checker
132+
.pyre/
133+
134+
# pytype static type analyzer
135+
.pytype/
136+
137+
# Cython debug symbols
138+
cython_debug/

‎src/api/api.py

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
import flask
2+
from tasks import tasks
3+
4+
app = flask.Flask(__name__)
5+
app.config["DEBUG"] = True
6+
app.register_blueprint(tasks)
7+
8+
@app.route("/api/version")
9+
def version():
10+
return "1.0"
11+
12+
app.run(port=8080)

0 commit comments

Comments
 (0)