inventory/DOCKER_README.md

Docker Containerization Guide

Overview

This inventory management system provides two Docker deployment options:

• Basic Setup: Single container using external database
• Full Setup: Complete stack with built-in MariaDB and Redis

Quick Start

Prerequisites

• Docker and Docker Compose installed
• At least 2GB RAM available (4GB recommended for full setup)
• Sufficient disk space for uploads and database

Deployment Options

Option 1: Basic Setup (External Database)

Perfect for production environments with existing database infrastructure.

1. Environment Configuration

# Copy and edit environment file
cp backend/.env.local backend/.env.local
nano backend/.env.local

Edit the .env.local file with your external database configuration:

# External Database Configuration
DB_HOST=your-external-db-host
DB_PORT=3306
DB_NAME=inventory_db
DB_USER=your-db-username
DB_PASS=your-db-password

# 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

2. Start the Application

docker-compose up -d

3. Access the Application

• Frontend: http://localhost:80
• Uses your external database

Option 2: Full Setup (Built-in Database + Cache)

Perfect for development, testing, or all-in-one deployments.

1. Start with Built-in Services

docker-compose -f docker-compose-with-services.yml --env-file .env.with-services up -d

2. Access the Application

• Frontend: http://localhost:80
• Database: MariaDB on port 3306
• Redis Cache: Redis on port 6379

3. Default Credentials

• Database: inventory_user / inventory_password
• Root Database: root / root_password
• Redis: Password protected with redis_password

Services Overview

Basic Setup Services

• inventory-app: Complete application (PHP + Apache + Vue.js)
• Volumes: Uploads directory mounted to host

Full Setup Services

• inventory-app: Complete application
• mariadb: MariaDB 10.11 database server
• redis: Redis 7 cache server
• Volumes: Database persistence, Redis persistence, Uploads directory

Configuration Details

Environment Variables

Basic Setup Variables

• DB_HOST: External database server hostname (required)
• DB_PORT: Database port (default: 3306)
• DB_NAME: Database name (default: inventory_db)
• DB_USER: Database username (required)
• DB_PASS: Database password (required)

Full Setup Variables

• DB_HOST: Database hostname (default: mariadb)
• DB_NAME: Database name (default: inventory_db)
• DB_USER: Database user (default: inventory_user)
• DB_PASS: Database password (default: inventory_password)
• MYSQL_ROOT_PASSWORD: MariaDB root password (default: root_password)
• REDIS_HOST: Redis hostname (default: redis)
• REDIS_PORT: Redis port (default: 6379)
• REDIS_PASSWORD: Redis password (default: redis_password)

Company Configuration

• COMPANY_NAME: Company name for invoices and reports
• COMPANY_ADDRESS: Company address
• COMPANY_CITY: Company city
• COMPANY_COUNTRY: Company country
• COMPANY_PHONE: Company phone number
• COMPANY_EMAIL: Company email
• COMPANY_Y_TUNNUS: Finnish business ID

File Upload Configuration

• UPLOAD_MAX_SIZE: Maximum file upload size (default: 10M)
• ALLOWED_FILE_TYPES: Allowed file extensions
• UPLOADS_PATH: Uploads directory path

Database Setup

For Basic Setup (External Database)

Create database and user on your external database server:

-- Create database and user (MySQL example)
CREATE DATABASE inventory_db;
CREATE USER 'your-username'@'%' IDENTIFIED BY 'your-password';
GRANT ALL PRIVILEGES ON inventory_db.* TO 'your-username'@'%';
FLUSH PRIVILEGES;

Import the complete database schema:

mysql -h your-db-host -u your-username -p inventory_db < backend/setup_database.sql

For Full Setup (Built-in Database)

Database is automatically created when containers start with the schema from backend/setup_database.sql.

Container Management

Start Services

# Basic setup
docker-compose up -d

# Full setup
docker-compose -f docker-compose-with-services.yml --env-file .env.with-services up -d

Stop Services

# Basic setup
docker-compose down

# Full setup
docker-compose -f docker-compose-with-services.yml down

View Logs

# Basic setup
docker-compose logs -f inventory-app

# Full setup
docker-compose -f docker-compose-with-services.yml logs -f

Rebuild Container

docker-compose up -d --build

Troubleshooting

Database Connection Issues

1. Verify database credentials in environment file
2. Check if database server is accessible
3. Ensure database user has proper permissions
4. For local development, check if MySQL socket exists

Port Conflicts

1. Change ports in environment variables
2. Stop conflicting services
3. Use docker ps to check running containers

File Upload Issues

1. Ensure uploads directory exists and is writable
2. Check file permissions on mounted volume
3. Verify UPLOAD_MAX_SIZE setting

Health Checks

# Check container health
docker-compose ps

# View health check logs
docker-compose logs inventory-app | grep health

• BACKEND_PORT: Backend service port (default: 8080)
• FRONTEND_PORT: Frontend service port (default: 3000)
• REDIS_PORT: Redis service port (default: 6379)

Company Information

• COMPANY_NAME: Your company name
• COMPANY_ADDRESS: Company address
• COMPANY_CITY: Company city
• COMPANY_POSTAL_CODE: Postal code
• COMPANY_COUNTRY: Country
• COMPANY_PHONE: Phone number
• COMPANY_EMAIL: Email address
• COMPANY_Y_TUNNUS: Finnish business ID

File Upload Configuration

• UPLOAD_MAX_SIZE: Maximum file upload size (default: 10M)
• ALLOWED_FILE_TYPES: Allowed file extensions
• UPLOADS_PATH: External path for uploads volume mount

Frontend Configuration

• VUE_APP_API_URL: Backend API URL for frontend

Volume Mounts

Uploads Directory

The uploads directory is mounted as an external volume to persist file uploads across container restarts:

volumes:
  uploads_data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ${UPLOADS_PATH:-./uploads}

Database Data

MySQL data is persisted in a Docker volume:

volumes:
  mysql_data:
    driver: local

Network Configuration

All services communicate through a dedicated Docker network:

networks:
  inventory-network:
    driver: bridge

Production Deployment

Security Considerations

1. Change all default passwords
2. Use HTTPS in production (configure SSL certificates)
3. Restrict database access to internal network only
4. Regularly update containers and dependencies
5. Implement proper backup strategy for database and uploads

Scaling

The architecture supports horizontal scaling:

• Frontend can be scaled by adding more Nginx containers behind a load balancer
• Backend can be scaled by adding more PHP containers
• Database can be moved to external managed service

Monitoring

Consider adding:

• Health checks for all services
• Log aggregation
• Performance monitoring
• Backup automation

Development

Local Development

For development, you can run services individually:

# Start only database
docker-compose up -d mysql

# Start backend with live reload
docker-compose up -d --build backend

# Start frontend with live reload
cd frontend && npm run serve

Debugging

View logs for specific services:

# Backend logs
docker-compose logs -f backend

# Frontend logs
docker-compose logs -f frontend

# Database logs
docker-compose logs -f mysql

Database Management

Connect to the database:

docker-compose exec mysql mysql -u inventory_user -p inventory_db

Troubleshooting

Common Issues

Database Connection Failed

1. Check if MySQL container is running: docker-compose ps
2. Verify database credentials in .env file
3. Check database logs: docker-compose logs mysql

Upload Directory Not Working

1. Ensure uploads directory exists on host
2. Check permissions: ls -la uploads/
3. Verify volume mount in docker-compose.yml

Frontend Not Loading

1. Check if backend is accessible: curl http://localhost:8080/api/company.php
2. Verify API URL configuration
3. Check frontend logs: docker-compose logs frontend

Performance Optimization

1. Enable Redis caching for frequently accessed data
2. Configure PHP OPcache for better performance
3. Use CDN for static assets
4. Implement database connection pooling

Maintenance

Updates

To update the application:

# Pull latest changes
git pull

# Rebuild and restart containers
docker-compose down
docker-compose up -d --build

Backups

Regular backups should include:

1. Database dump: docker-compose exec mysql mysqldump -u root -p inventory_db
2. Uploads directory: tar -czf uploads_backup.tar.gz uploads/

Cleanup

Remove unused containers and images:

docker system prune -a
docker volume prune

Support

For issues and questions, refer to the application logs or contact your system administrator.