# 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**
   ```bash
   cd /srv/quality_app-v2
   ```

2. **Create configuration file**
   ```bash
   cp .env.example .env
   # Edit .env with your settings if needed
   ```

3. **Deploy with Docker Compose**
   ```bash
   # 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:

```ini
# 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
```bash
docker-compose up -d
```

### Stop Services
```bash
docker-compose down
```

### View Logs
```bash
# All services
docker-compose logs -f

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

### Execute Commands in Container
```bash
# 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
```bash
docker-compose build --no-cache
```

### Health Status
```bash
docker-compose ps
```

## Database Management

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

```bash
docker-compose exec app python init_db.py
```

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

### Restore Database
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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:
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   ```

2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

3. Configure database in .env

4. Initialize database:
   ```bash
   python init_db.py
   ```

5. Run development server:
   ```bash
   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