320 lines
6.9 KiB
Markdown
320 lines
6.9 KiB
Markdown
# Recticel Quality Application - Docker Deployment Guide
|
|
|
|
## 📋 Overview
|
|
|
|
This is a complete Docker-based deployment solution for the Recticel Quality Application. It includes:
|
|
- **Flask Web Application** (Python 3.10)
|
|
- **MariaDB 11.3 Database** with automatic initialization
|
|
- **Gunicorn WSGI Server** for production-ready performance
|
|
- **Automatic database schema setup** using existing setup scripts
|
|
- **Superadmin user seeding** for immediate access
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
- Docker Engine 20.10+
|
|
- Docker Compose 2.0+
|
|
- At least 2GB free disk space
|
|
- Ports 8781 and 3306 available (or customize in .env)
|
|
|
|
### 1. Clone and Prepare
|
|
|
|
```bash
|
|
cd /srv/quality_recticel
|
|
```
|
|
|
|
### 2. Configure Environment (Optional)
|
|
|
|
Create a `.env` file from the example:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` to customize settings:
|
|
```env
|
|
MYSQL_ROOT_PASSWORD=your_secure_root_password
|
|
DB_PORT=3306
|
|
APP_PORT=8781
|
|
INIT_DB=true
|
|
SEED_DB=true
|
|
```
|
|
|
|
### 3. Build and Deploy
|
|
|
|
Start all services:
|
|
|
|
```bash
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
This will:
|
|
1. ✅ Build the Flask application Docker image
|
|
2. ✅ Pull MariaDB 11.3 image
|
|
3. ✅ Create and initialize the database
|
|
4. ✅ Run all database schema creation scripts
|
|
5. ✅ Seed the superadmin user
|
|
6. ✅ Start the web application on port 8781
|
|
|
|
### 4. Verify Deployment
|
|
|
|
Check service status:
|
|
```bash
|
|
docker-compose ps
|
|
```
|
|
|
|
View logs:
|
|
```bash
|
|
# All services
|
|
docker-compose logs -f
|
|
|
|
# Just the web app
|
|
docker-compose logs -f web
|
|
|
|
# Just the database
|
|
docker-compose logs -f db
|
|
```
|
|
|
|
### 5. Access the Application
|
|
|
|
Open your browser and navigate to:
|
|
```
|
|
http://localhost:8781
|
|
```
|
|
|
|
**Default Login:**
|
|
- Username: `superadmin`
|
|
- Password: `superadmin123`
|
|
|
|
## 🔧 Management Commands
|
|
|
|
### Start Services
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
### Stop Services
|
|
```bash
|
|
docker-compose down
|
|
```
|
|
|
|
### Stop and Remove All Data (including database)
|
|
```bash
|
|
docker-compose down -v
|
|
```
|
|
|
|
### Restart Services
|
|
```bash
|
|
docker-compose restart
|
|
```
|
|
|
|
### View Real-time Logs
|
|
```bash
|
|
docker-compose logs -f
|
|
```
|
|
|
|
### Rebuild After Code Changes
|
|
```bash
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
### Access Database Console
|
|
```bash
|
|
docker-compose exec db mariadb -u trasabilitate -p trasabilitate
|
|
# Password: Initial01!
|
|
```
|
|
|
|
### Execute Commands in App Container
|
|
```bash
|
|
docker-compose exec web bash
|
|
```
|
|
|
|
## 📁 Data Persistence
|
|
|
|
The following data is persisted across container restarts:
|
|
|
|
- **Database Data:** Stored in Docker volume `mariadb_data`
|
|
- **Application Logs:** Mapped to `./logs` directory
|
|
- **Instance Config:** Mapped to `./instance` directory
|
|
|
|
## 🔐 Security Considerations
|
|
|
|
### Production Deployment Checklist:
|
|
|
|
1. **Change Default Passwords:**
|
|
- Update `MYSQL_ROOT_PASSWORD` in `.env`
|
|
- Update database password in `docker-compose.yml`
|
|
- Change superadmin password after first login
|
|
|
|
2. **Use Environment Variables:**
|
|
- Never commit `.env` file to version control
|
|
- Use secrets management for production
|
|
|
|
3. **Network Security:**
|
|
- If database access from host is not needed, remove the port mapping:
|
|
```yaml
|
|
# Comment out in docker-compose.yml:
|
|
# ports:
|
|
# - "3306:3306"
|
|
```
|
|
|
|
4. **SSL/TLS:**
|
|
- Configure reverse proxy (nginx/traefik) for HTTPS
|
|
- Update gunicorn SSL configuration if needed
|
|
|
|
5. **Firewall:**
|
|
- Only expose necessary ports
|
|
- Use firewall rules to restrict access
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Database Connection Issues
|
|
|
|
If the app can't connect to the database:
|
|
|
|
```bash
|
|
# Check database health
|
|
docker-compose exec db healthcheck.sh --connect
|
|
|
|
# Check database logs
|
|
docker-compose logs db
|
|
|
|
# Verify database is accessible
|
|
docker-compose exec db mariadb -u trasabilitate -p -e "SHOW DATABASES;"
|
|
```
|
|
|
|
### Application Not Starting
|
|
|
|
```bash
|
|
# Check application logs
|
|
docker-compose logs web
|
|
|
|
# Verify database initialization
|
|
docker-compose exec web python3 -c "import mariadb; print('MariaDB module OK')"
|
|
|
|
# Restart with fresh initialization
|
|
docker-compose down
|
|
docker-compose up -d
|
|
```
|
|
|
|
### Port Already in Use
|
|
|
|
If port 8781 or 3306 is already in use, edit `.env`:
|
|
|
|
```env
|
|
APP_PORT=8782
|
|
DB_PORT=3307
|
|
```
|
|
|
|
Then restart:
|
|
```bash
|
|
docker-compose down
|
|
docker-compose up -d
|
|
```
|
|
|
|
### Reset Everything
|
|
|
|
To start completely fresh:
|
|
|
|
```bash
|
|
# Stop and remove all containers, networks, and volumes
|
|
docker-compose down -v
|
|
|
|
# Remove any local data
|
|
rm -rf logs/* instance/external_server.conf
|
|
|
|
# Start fresh
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
## 🔄 Updating the Application
|
|
|
|
### Update Application Code
|
|
|
|
1. Make your code changes
|
|
2. Rebuild and restart:
|
|
```bash
|
|
docker-compose up -d --build web
|
|
```
|
|
|
|
### Update Database Schema
|
|
|
|
If you need to run migrations or schema updates:
|
|
|
|
```bash
|
|
docker-compose exec web python3 /app/app/db_create_scripts/setup_complete_database.py
|
|
```
|
|
|
|
## 📊 Monitoring
|
|
|
|
### Health Checks
|
|
|
|
Both services have health checks configured:
|
|
|
|
```bash
|
|
# Check overall status
|
|
docker-compose ps
|
|
|
|
# Detailed health status
|
|
docker inspect recticel-app | grep -A 10 Health
|
|
docker inspect recticel-db | grep -A 10 Health
|
|
```
|
|
|
|
### Resource Usage
|
|
|
|
```bash
|
|
# View resource consumption
|
|
docker stats recticel-app recticel-db
|
|
```
|
|
|
|
## 🏗️ Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ Docker Compose Network │
|
|
│ │
|
|
│ ┌──────────────┐ ┌─────────────┐ │
|
|
│ │ MariaDB │ │ Flask App │ │
|
|
│ │ Container │◄─┤ Container │ │
|
|
│ │ │ │ │ │
|
|
│ │ Port: 3306 │ │ Port: 8781 │ │
|
|
│ └──────┬───────┘ └──────┬──────┘ │
|
|
│ │ │ │
|
|
└─────────┼─────────────────┼─────────┘
|
|
│ │
|
|
▼ ▼
|
|
[Volume: [Logs &
|
|
mariadb_data] Instance]
|
|
```
|
|
|
|
## 📝 Environment Variables
|
|
|
|
### Database Configuration
|
|
- `MYSQL_ROOT_PASSWORD`: MariaDB root password
|
|
- `DB_HOST`: Database hostname (default: `db`)
|
|
- `DB_PORT`: Database port (default: `3306`)
|
|
- `DB_NAME`: Database name (default: `trasabilitate`)
|
|
- `DB_USER`: Database user (default: `trasabilitate`)
|
|
- `DB_PASSWORD`: Database password (default: `Initial01!`)
|
|
|
|
### Application Configuration
|
|
- `FLASK_ENV`: Flask environment (default: `production`)
|
|
- `FLASK_APP`: Flask app entry point (default: `run.py`)
|
|
- `APP_PORT`: Application port (default: `8781`)
|
|
|
|
### Initialization Flags
|
|
- `INIT_DB`: Run database initialization (default: `true`)
|
|
- `SEED_DB`: Seed superadmin user (default: `true`)
|
|
|
|
## 🆘 Support
|
|
|
|
For issues or questions:
|
|
1. Check the logs: `docker-compose logs -f`
|
|
2. Verify environment configuration
|
|
3. Ensure all prerequisites are met
|
|
4. Review this documentation
|
|
|
|
## 📄 License
|
|
|
|
[Your License Here]
|