quality_recticel/DOCKER_DEPLOYMENT.md

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

cd /srv/quality_recticel

2. Configure Environment (Optional)

Create a .env file from the example:

cp .env.example .env

Edit .env to customize settings:

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:

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:

docker-compose ps

View logs:

# 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

docker-compose up -d

Stop Services

docker-compose down

Stop and Remove All Data (including database)

docker-compose down -v

Restart Services

docker-compose restart

View Real-time Logs

docker-compose logs -f

Rebuild After Code Changes

docker-compose up -d --build

Access Database Console

docker-compose exec db mariadb -u trasabilitate -p trasabilitate
# Password: Initial01!

Execute Commands in App Container

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:

     # 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:

# 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

# 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:

APP_PORT=8782
DB_PORT=3307

Then restart:

docker-compose down
docker-compose up -d

Reset Everything

To start completely fresh:

# 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:

   docker-compose up -d --build web
   

Update Database Schema

If you need to run migrations or schema updates:

docker-compose exec web python3 /app/app/db_create_scripts/setup_complete_database.py

📊 Monitoring

Health Checks

Both services have health checks configured:

# 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

# 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]