quality_app-v2/documentation

Quality App v2 - Docker Setup & Deployment Guide

Overview

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

1. Clone/Copy the project

   cd /srv/quality_app-v2
   

2. Create configuration file

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

3. Deploy with Docker Compose

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

4. 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

1. users - User accounts
2. user_credentials - Password hashes
3. quality_inspections - Quality check records
4. application_settings - App configuration

Features

Login System

• 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

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

Performance Optimization

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

Monitoring

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

Scaling

For production scale-out:

1. Use load balancer (Nginx, HAProxy)
2. Multiple app instances with shared database
3. Persistent volumes for data
4. 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):

1. Create virtual environment:

   python3 -m venv venv
   source venv/bin/activate
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure database in .env

4. Initialize database:

   python init_db.py
   

5. 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