Initial commit: Quality App v2 - FG Scan Module with Reports
This commit is contained in:
Quality App Developer
386
documentation/README.md
Normal file
386
documentation/README.md
Normal file
@@ -0,0 +1,386 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user