Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/marincervinschi/qr-flask
Dynamik QR Code is a Flask web app for generating and managing dynamic QR codes. Admins can update URLs without changing the QR code. Built for learning, it explores Flask, MySQL, and Docker while focusing on secure admin access and dynamic redirects.
https://github.com/marincervinschi/qr-flask
actions docker docker-compose dockerfile environment environment-variables flask flask-application flask-web mysql mysql-database nginx proxy pyhton pytest python3 schema test testing workflow
Last synced: 21 days ago
JSON representation
Dynamik QR Code is a Flask web app for generating and managing dynamic QR codes. Admins can update URLs without changing the QR code. Built for learning, it explores Flask, MySQL, and Docker while focusing on secure admin access and dynamic redirects.
- Host: GitHub
- URL: https://github.com/marincervinschi/qr-flask
- Owner: MarinCervinschi
- License: mit
- Created: 2024-11-25T16:08:58.000Z (29 days ago)
- Default Branch: master
- Last Pushed: 2024-12-02T10:33:35.000Z (22 days ago)
- Last Synced: 2024-12-02T10:33:50.883Z (22 days ago)
- Topics: actions, docker, docker-compose, dockerfile, environment, environment-variables, flask, flask-application, flask-web, mysql, mysql-database, nginx, proxy, pyhton, pytest, python3, schema, test, testing, workflow
- Language: Python
- Homepage:
- Size: 570 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# QR Flask Project
## Overview
Dynamik QR Code is a simple yet robust Flask-based web application designed as a learning project to explore modern web technologies and frameworks. The application generates dynamic QR codes that contain a URL, which can be updated without regenerating the QR code itself. This functionality makes it a practical tool for managing redirects while ensuring QR codes remain static for end users.
### Key Features
1. Dynamic QR Codes:
The QR codes generated by this app are tied to a URL stored on the server. Admins can update this URL, and the changes will reflect immediately without the need to regenerate the QR code.
2. Admin-Only Access:
The app is designed solely for administrators. It includes private and protected pages, ensuring the functionality remains hidden from end users. The general public or users scanning the QR codes are unaware that their requests pass through this system before being redirected to the final destination.
3. Learning-Focused:
This project serves as a practical platform to study and experiment with:
- Flask Framework: For creating a Python-based web app.
- Session Management: Secure handling of user sessions for admin pages.
- Pytest and Coverage.py: For unit testing and code coverage.
- MySQL Integration: For dynamic data storage and retrieval.
- Docker and Docker Compose: To simplify deployment and ensure consistency across environments.
4. Seamless User Experience:
Users scanning the QR codes will experience a direct redirection to the final link, unaware of the underlying intermediate step managed by the app.
### Get Started
- [Installation without setup](#installation-without-setup)
- [ON WINDOWS](#on-windows)
- [ON UNIX](#on-unix)
- [Run Flask To Develop Locally](#run-flask-to-develop-locally)
- [Configuration](#configuration)
- [Usage](#usage)
- [Testing](#testing)
- [Deployment Structure](#deployment-structure)
- [Deployment with Docker and Docker Compose](#deployment-with-docker-and-docker-compose)
## Project Structure
```plaintext
.
├── LICENSE
├── README.md
├── app
│ ├── __init__.py
│ ├── config.py
│ ├── db.py
│ ├── routes
│ │ ├── __init__.py
│ │ ├── auth.py
│ │ ├── dashboard.py
│ │ └── main.py
│ ├── static
│ │ ├── css
│ │ │ ├── dashboard.css
│ │ │ ├── error.css
│ │ │ └── style.css
│ │ ├── js
│ │ │ └── scripts.js
│ │ └── media
│ │ ├── logo.png
│ │ └── qr.png
│ └── templates
│ ├── auth
│ │ ├── admin.html
│ │ └── dashboard.html
│ ├── base.html
│ ├── error.html
│ └── index.html
├── tests
│ ├── conftest.py
│ ├── data.sql
│ ├── test_auth.py
│ ├── test_dashboard.py
│ ├── test_db.py
│ ├── test_factory.py
│ └── test_main.py
├── run.py
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── schema.sql
├── start.bat
├── start.sh
├── stop.bat
└── stop.sh
```
## Installation without setup
Clone the repository:
```bash
git clone https://github.com/yourusername/QR-flask.git
cd QR-flask
```
### ON WINDOWS
- First, change permissions for the `start.bat` & `stop.bat` files:
```powershell
icacls start.bat /grant Everyone:F
```
- Then, run the `start.bat` file to start the application:
```powershell
.\start.bat
```
- To stop the application, run the `stop.bat` file:
```powershell
.\stop.bat
```
---
### ON UNIX
- First, change permissions for the `start.sh` & `stop.sh` files:
```bash
chmod +x start.sh
```
- Then, run the `start.sh` file to start the application:
```bash
./start.sh
```
- To stop the application, run the `stop.sh` file:
```bash
./stop.sh
```
---
> **⚠️ Important Warning:**
>
> The `start.sh` and `start.bat` scripts create the `.flask.env` and `.mysql.env` files with default values. REMEMBER to change the default values in the `.env` files to secure your application.
# Run Flask To Develop Locally
1. Clone the repository:
```bash
git clone https://github.com/yourusername/QR-flask.git
cd QR-flask
```
2. Create a virtual environment:
```bash
python3 -m venv venv
source venv/bin/activate
```
3. Install the dependencies:
```bash
pip install -r requirements.txt
```
## Configuration
### Flask Environment Variables
Create a `.flask.env` file in the project root with the following content:
```bash
FLASK_APP=app # The app name
FLASK_RUN_PORT=5000 # Port for the app
FLASK_RUN_HOST=127.0.0.1 # App host (e.g., localhost or 127.0.0.1)
APP_URL=http://127.0.0.1:5000 # URL for the app and QR code
SECRET_KEY=your_secret_key # Secret key for Flask
PERMANENT_SESSION_LIFETIME=30 # Session lifetime in minutes
```
### MySQL Environment Variables
Create a `.mysql.env` file in the project root with the following content:
```bash
MYSQL_ROOT_PASSWORD=root # Root password
MYSQL_HOST=qr-db # Database host (e.g., service name in Docker or localhost)
MYSQL_PORT=3306 # Database port
MYSQL_PASSWORD=root # User password
MYSQL_DB=qr_db # Database name
```
Note: These `.env` files are included in .`gitignore` to protect sensitive data.
## Usage
1. Run the Flask application:
```bash
flask run
```
or
```bash
python run.py
```
2. Access the application:
Open your web browser and go to `http://127.0.0.1:5000`.
3. To stop the Flask application, press `Ctrl+C` in the terminal.
## Testing
1. Run tests using pytest:
```bash
python -m pytest
```
3. Generate a coverage report:
```bash
coverage run -m pytest
coverage report
```
4. To generate an HTML coverage report:
```bash
coverage html
```
Open `htmlcov/index.html` in your web browser to view the report.
## Deployment Structure
```plaintext
.
└── docker-compose.yml
├── qr-db:
│ └── mysql:8.4
└── qr-app:
├── build .
└── depends_on:
└── qr-db
```
## Deployment with Docker and Docker Compose
1. Build and start the containers:
```bash
docker-compose up --build -d
```
The `-d` flag runs the containers in the background.
2. Open your web browser and go to `http://localhost`.
3. To stop the containers, run:
```bash
docker-compose down -v
```
The `-v` flag removes the volumes associated with the containers.
4. To view the logs of a specific service, run:
```bash
docker-compose logs
```
5. To run commands inside a running container, use:
```bash
docker-compose exec
```
6. To connect to the MySQL database, run:
```bash
docker-compose exec qr-db mysql -u root -p qr_db
```
Enter the password when prompted.
7. To view the tables in the database, run:
```bash
mysql> SHOW TABLES;
```
## Contributing
Contributions are welcome! Please open an issue or submit a pull request.
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.