387 lines
9.7 KiB
Markdown
387 lines
9.7 KiB
Markdown
# 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
|