Quality App v2 is a modern, robust Flask web application with MariaDB database integration. It features a comprehensive authentication system, modular architecture, and containerized deployment.

Quick Start

Prerequisites

Docker (20.10+)
Docker Compose (1.29+)
4GB RAM minimum
5GB disk space minimum

Quick Deployment

Clone/Copy the project
```
cd /srv/quality_app-v2
```

Create configuration file

cp .env.example .env
# Edit .env with your settings if needed

Deploy with Docker Compose

# Make the deploy script executable
chmod +x quick-deploy.sh

# Run the deployment
./quick-deploy.sh

Access the application
- URL: http://localhost:8080
- Username: admin
- Password: admin123

File Structure

quality_app-v2/
├── app/                          # Main application package
│   ├── __init__.py              # App factory and initialization
│   ├── auth.py                  # Authentication utilities
│   ├── config.py                # Configuration management
│   ├── database.py              # Database connection pool
│   ├── routes.py                # Main routes (login, dashboard)
│   ├── modules/                 # Feature modules
│   │   ├── quality/             # Quality module
│   │   │   ├── __init__.py
│   │   │   └── routes.py
│   │   └── settings/            # Settings module
│   │       ├── __init__.py
│   │       └── routes.py
│   ├── models/                  # Database models (expandable)
│   ├── static/                  # Static files
│   │   ├── css/                 # Stylesheets
│   │   │   ├── base.css
│   │   │   └── login.css
│   │   ├── js/                  # JavaScript
│   │   │   └── base.js
│   │   └── images/              # Images and assets
│   └── templates/               # HTML templates
│       ├── base.html            # Base template
│       ├── login.html           # Login page
│       ├── dashboard.html       # Dashboard
│       ├── profile.html         # User profile
│       ├── modules/             # Module templates
│       │   ├── quality/
│       │   │   ├── index.html
│       │   │   ├── inspections.html
│       │   │   └── reports.html
│       │   └── settings/
│       │       ├── index.html
│       │       ├── general.html
│       │       ├── users.html
│       │       └── database.html
│       └── errors/              # Error pages
│           ├── 404.html
│           ├── 500.html
│           └── 403.html
├── data/                        # Persistent data (Docker volumes)
│   ├── db/                      # Database backups
│   ├── logs/                    # Application logs
│   ├── uploads/                 # User uploads
│   └── backups/                 # Database backups
├── Dockerfile                   # Docker image definition
├── docker-compose.yml           # Multi-container orchestration
├── docker-entrypoint.sh         # Container startup script
├── gunicorn.conf.py             # Gunicorn configuration
├── requirements.txt             # Python dependencies
├── run.py                       # Development entry point
├── wsgi.py                      # Production WSGI entry point
├── init_db.py                   # Database initialization
├── quick-deploy.sh              # Quick deployment script
├── .env.example                 # Environment variables template
├── .gitignore                   # Git ignore file
└── README.md                    # This file

Configuration

Environment Variables

Edit .env file to customize:

# Flask Configuration
FLASK_ENV=production              # Set to 'development' for debug mode
FLASK_DEBUG=False
SECRET_KEY=your-secret-key        # Change in production!

# Database Configuration
DB_HOST=mariadb                   # MariaDB service name
DB_PORT=3306
DB_USER=quality_user
DB_PASSWORD=your-password         # Change in production!
DB_NAME=quality_db

# Application Configuration
APP_PORT=8080
APP_HOST=0.0.0.0

# Logging
LOG_LEVEL=INFO

Docker Compose Services

MariaDB Service

Container: quality_app_mariadb
Port: 3306 (internal), configurable external
Volume: mariadb_data (persistent)
Health Check: Enabled

Flask Application Service

Container: quality_app_v2
Port: 8080 (configurable)
Volumes:
- Application code
- Logs: /app/data/logs
- Uploads: /app/data/uploads
- Backups: /app/data/backups
Health Check: Enabled

Common Commands

Start Services

docker-compose up -d

Stop Services

docker-compose down

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f app
docker-compose logs -f mariadb

Execute Commands in Container

# Run Python command
docker-compose exec app python init_db.py

# Access container shell
docker-compose exec app /bin/bash

# Access MariaDB CLI
docker-compose exec mariadb mariadb -u quality_user -p quality_db

Rebuild Images

docker-compose build --no-cache

Health Status

docker-compose ps

Database Management

Initialize Database

The database is initialized automatically on first startup. To reinitialize:

docker-compose exec app python init_db.py

Backup Database

docker-compose exec mariadb mariadb-dump -u quality_user -p quality_db > backup_$(date +%Y%m%d_%H%M%S).sql

Restore Database

docker-compose exec -T mariadb mariadb -u quality_user -p quality_db < backup_20240125_120000.sql

Default Credentials

IMPORTANT: Change these immediately after first login!

Username: admin
Password: admin123
Role: admin

Default Database Tables

users - User accounts
user_credentials - Password hashes
quality_inspections - Quality check records
application_settings - App configuration

Features

Secure password hashing (SHA256)
Session management
Role-based access control
User profile management

Dashboard

Welcome section with current date/time
Quick statistics cards
Module launcher with descriptions
Recent activity feed

Quality Module

Inspection management
Quality reports and statistics
Pass/fail tracking

Settings Module

General application settings
User management interface
Database configuration view

Security Features

CSRF protection via Flask
Secure session cookies
SQL injection prevention via parameterized queries
Password hashing with salt

Production Deployment

HTTPS Configuration

Obtain SSL certificates
Place certificate files in a ssl/ directory
Configure Nginx reverse proxy (uncomment in docker-compose.yml)

Performance Optimization

Increase MariaDB connection limit in docker-compose.yml
Adjust Gunicorn workers in gunicorn.conf.py
Enable production-grade reverse proxy (Nginx)
Configure Redis caching (future enhancement)

Monitoring

Check logs: docker-compose logs -f
Monitor container health: docker-compose ps
Database query logs available in MariaDB container

Scaling

For production scale-out:

Use load balancer (Nginx, HAProxy)
Multiple app instances with shared database
Persistent volumes for data
Database replication for high availability

Troubleshooting

MariaDB Connection Failed

# Check if MariaDB is running
docker-compose ps

# View MariaDB logs
docker-compose logs mariadb

# Restart MariaDB
docker-compose restart mariadb

Application Won't Start

# Check application logs
docker-compose logs app

# Verify database initialization
docker-compose exec app python init_db.py

# Check environment variables
docker-compose config

Port Already in Use

# Change port in .env file
APP_PORT=8081

# Rebuild and restart
docker-compose down
docker-compose up -d

Development

For local development (without Docker):

Create virtual environment:

python3 -m venv venv
source venv/bin/activate

Install dependencies:
```
pip install -r requirements.txt
```
Configure database in .env
Initialize database:
```
python init_db.py
```
Run development server:
```
python run.py
```

Project Structure Philosophy

Modular Design: Each feature is in its own module
Separation of Concerns: Routes, models, and business logic separated
Scalability: Easy to add new modules and features
Security: Built-in authentication and authorization
Containerization: Full Docker support for easy deployment

Future Enhancements

API endpoints (REST/GraphQL)
Advanced reporting and analytics
Email notifications
User activity logging
Data export (Excel, PDF)
Advanced searching and filtering
Dashboard customization
Multi-language support
Two-factor authentication
Audit trail system

Support & Documentation

For more information:

Check Docker Compose documentation: https://docs.docker.com/compose/
Flask documentation: https://flask.palletsprojects.com/
MariaDB documentation: https://mariadb.com/kb/

License

[Specify your license here]

Author

Quality App Team - 2026

README.md

Quality App v2 - Docker Setup & Deployment Guide

Overview