inventory/DOCKER_DEPLOYMENT.md

Docker Deployment Guide

🐳 Complete Inventory Management System in One Container

This guide explains how to deploy the complete inventory management system using Docker and Docker Compose.

📋 Prerequisites

• Docker 20.10+ and Docker Compose 2.0+
• At least 2GB RAM available
• At least 10GB free disk space

🚀 Quick Start

1. Clone and Setup

git clone <repository-url>
cd inventory

2. Configure Environment

# Copy environment file
cp .env.example .env

# Edit configuration (optional)
nano .env

3. Build and Deploy

# Make build script executable
chmod +x build.sh

# Run the build script
./build.sh

4. Access Application

• Frontend: http://localhost
• API: http://localhost/api
• Database: External database (configured in .env)

🏗️ Architecture

Single Container Solution

The Docker setup creates a single container that includes:

• Apache Web Server with PHP 8.1
• Vue.js Frontend (built and served)
• PHP Backend API with all endpoints
• External Database (user-provided MySQL/MariaDB)
• Redis Cache (optional)

Container Structure

inventory-app (main container)
├── Apache Web Server
├── PHP Backend (/var/www/html/api)
├── Vue.js Frontend (/var/www/html/frontend/dist)
├── Uploads (/var/www/html/uploads)
└── Configuration

inventory-redis (optional)
└── Redis 7 Cache

External Database (user-provided)
└── MySQL/MariaDB Database

⚙️ Configuration

Environment Variables (.env)

# Database Configuration (External)
DB_HOST=your-external-db-host # Your database server
DB_PORT=3306
DB_NAME=inventory_db
DB_USER=your-db-username
DB_PASS=your-db-password

# Application Port
APP_PORT=80                   # Web server port

# Redis (optional)
REDIS_PORT=6379

# Company Information
COMPANY_NAME=Your Company Name
COMPANY_ADDRESS=123 Business Street
COMPANY_CITY=Helsinki
COMPANY_POSTAL_CODE=00100
COMPANY_COUNTRY=Finland
COMPANY_PHONE=+358 123 456 789
COMPANY_EMAIL=info@yourcompany.com
COMPANY_Y_TUNNUS=1234567-8

# File Upload Configuration
UPLOAD_MAX_SIZE=10M
ALLOWED_FILE_TYPES=pdf,doc,docx,xls,xlsx,jpg,jpeg,png,gif
UPLOADS_PATH=./uploads

🛠️ Docker Compose Services

inventory-app

• Purpose: Main application container
• Image: Built from Dockerfile
• Ports: 80:80
• Features: PHP backend + Vue.js frontend
• Database: Connects to external database via environment variables

redis (optional)

• Purpose: Caching layer
• Image: redis:7-alpine
• Ports: 6379:6379
• Volume: Persistent data storage

🗄️ External Database Setup

Database Requirements

• MySQL 8.0+ or MariaDB 10.5+
• Network Access: Container must be able to reach database host
• Schema: Run backend/migrate_complete.sql to create database schema
• Permissions: User needs CREATE, SELECT, INSERT, UPDATE, DELETE privileges

Database Setup Steps

# 1. Create database
mysql -u root -p -e "CREATE DATABASE inventory_db;"

# 2. Create user
mysql -u root -p -e "CREATE USER 'inventory_db'@'%' IDENTIFIED BY 'your_password';"

# 3. Grant permissions
mysql -u root -p -e "GRANT ALL PRIVILEGES ON inventory_db.* TO 'inventory_db'@'%';"

# 4. Import schema
mysql -u inventory_db -p inventory_db < backend/migrate_complete.sql

# 5. Flush privileges
mysql -u root -p -e "FLUSH PRIVILEGES;"

📁 File Structure

inventory/
├── Dockerfile                 # Multi-stage build (Node.js + PHP)
├── docker-compose.yml         # Container orchestration
├── docker/
│   └── apache.conf           # Apache configuration
├── backend/
│   ├── api/                  # PHP API endpoints
│   ├── config/               # Configuration files
│   ├── models/               # PHP models
│   └── migrate_complete.sql  # Database schema (for external DB)
├── frontend/
│   ├── src/                  # Vue.js source code
│   ├── dist/                 # Built frontend (generated)
│   └── package.json          # Node.js dependencies
├── uploads/                  # File upload directory
├── .env.example              # Environment template
├── .env                      # Environment configuration
└── build.sh                  # Build script

🔧 Management Commands

Start Application

docker-compose up -d

Stop Application

docker-compose down

View Logs

# All logs
docker-compose logs

# Specific service logs
docker-compose logs inventory-app
docker-compose logs db
docker-compose logs redis

# Follow logs
docker-compose logs -f inventory-app

Rebuild Application

# Force rebuild without cache
docker-compose build --no-cache

# Rebuild specific service
docker-compose build inventory-app

Database Management

# Access external database
mysql -h your-external-db-host -u your-db-username -p inventory_db

# Backup external database
mysqldump -h your-external-db-host -u your-db-username inventory_db > backup.sql

# Restore external database
mysql -h your-external-db-host -u your-db-username inventory_db < backup.sql

# Test connection from container
docker-compose exec inventory-app php -r "echo 'Testing DB connection...';"

Container Management

# List containers
docker-compose ps

# Access container shell
docker-compose exec inventory-app bash

# Restart specific service
docker-compose restart inventory-app

# Update environment variables
docker-compose down
# Edit .env file
docker-compose up -d

🚨 Troubleshooting

Common Issues

1. Database Connection Failed

# Check application logs
docker-compose logs inventory-app

# Test database connectivity from container
docker-compose exec inventory-app ping your-external-db-host

# Test database connection manually
docker-compose exec inventory-app php -r "
try {
    \$pdo = new PDO('mysql:host=your-external-db-host;dbname=inventory_db', 'your-db-username', 'your-db-password');
    echo 'Database connection successful';
} catch (Exception \$e) {
    echo 'Database connection failed: ' . \$e->getMessage();
}
"

# Verify database schema exists
mysql -h your-external-db-host -u your-db-username -p inventory_db -e "SHOW TABLES;"

2. Frontend Not Loading

# Check application logs
docker-compose logs inventory-app

# Rebuild frontend
docker-compose build --no-cache inventory-app

# Check Apache configuration
docker-compose exec inventory-app apache2ctl -M

3. File Upload Issues

# Check uploads directory permissions
docker-compose exec inventory-app ls -la /var/www/html/uploads

# Fix permissions
docker-compose exec inventory-app chown -R www-data:www-data /var/www/html/uploads
docker-compose exec inventory-app chmod -R 755 /var/www/html/uploads

4. API Not Responding

# Test API endpoint
curl http://localhost/api/company.php

# Check Apache status
docker-compose exec inventory-app service apache2 status

# Restart Apache
docker-compose exec inventory-app service apache2 restart

Health Checks

The application includes health checks:

• inventory-app: Tests /api/company.php endpoint
• redis: Tests Redis connectivity (optional)

View health status:

docker-compose ps

🔒 Security Considerations

Production Deployment

1. Change Default Passwords: Update database passwords in .env
2. Use HTTPS: Configure SSL/TLS termination
3. Network Isolation: Use custom networks
4. Resource Limits: Set memory and CPU limits
5. Regular Updates: Keep Docker images updated

Environment Security

# Secure .env file
chmod 600 .env

# Use secrets for sensitive data
echo "DB_PASSWORD=your_secure_password" > .env.secret

📈 Performance Optimization

Production Optimizations

1. Enable Redis Caching: Configure Redis for session storage
2. Database Optimization: Use persistent connections
3. Frontend Caching: Enable browser caching
4. Load Balancing: Use multiple containers behind a load balancer

Monitoring

# Monitor resource usage
docker stats

# Monitor disk usage
docker-compose exec inventory-app df -h

# Monitor memory usage
docker-compose exec inventory-app free -m

🔄 Updates and Maintenance

Updating Application

# Pull latest code
git pull

# Rebuild and restart
docker-compose build --no-cache
docker-compose up -d

# Run database migrations if needed
docker-compose exec db mysql -u inventory_db inventory_db < migration.sql

Backup Strategy

# Backup database
docker-compose exec db mysqldump -u inventory_db inventory_db > backup_$(date +%Y%m%d).sql

# Backup uploads
tar -czf uploads_$(date +%Y%m%d).tar.gz uploads/

# Backup configuration
cp .env .env.backup

📞 Support

For issues with the Docker deployment:

1. Check the troubleshooting section above
2. Review container logs: docker-compose logs
3. Verify environment configuration
4. Check system resources (memory, disk space)

🎉 Success!

Your inventory management system is now running in Docker with:

• ✅ Complete frontend and backend in one container
• ✅ Automatic database setup and migration
• ✅ File upload functionality
• ✅ Timer management and work hours
• ✅ Persistent data storage
• ✅ Health monitoring
• ✅ Easy deployment and management