Docker Setup - CompuTécnicos

Overview

CompuTécnicos uses Docker and Docker Compose to provide a consistent development and deployment environment. The application runs in isolated containers with all dependencies pre-configured.

Architecture

The Docker setup consists of three main services:

Services

app - PHP/Apache Application

Image: PHP 8.2 with Apache
Port: 8080 (configurable via APP_PORT)
Features:
- PHP extensions: PDO, MySQLi, GD, Zip, Intl, mbstring, XML
- Composer for dependency management
- Apache with mod_rewrite enabled
- Persistent uploads and logs volumes
Dependencies: dompdf, PhpSpreadsheet, Google API Client

db - MySQL Database

Image: MySQL 8.0
Port: 3306 (configurable via DB_PORT)
Features:
- UTF-8 (utf8mb4) character set
- Automatic schema initialization
- Health checks for reliable startup
- Persistent data volume
Configuration: 64MB max packet size, native password authentication

phpmyadmin - Database Management

Image: phpMyAdmin latest
Port: 8081 (configurable via PMA_PORT)
Profile: dev (optional, for development only)
Access: Web-based MySQL management interface

Environment Configuration

Environment Variables

The .env file controls all configuration aspects:

# External ports for accessing services
APP_PORT=8080        # Web application
DB_PORT=3306         # MySQL database
PMA_PORT=8081        # phpMyAdmin

Creating Your Configuration

Copy Example File

cp .env.example .env

Edit Variables

Open .env in your text editor and update the values:

nano .env
# or
vim .env
# or use your preferred editor

Secure Production Values

For production deployments, always change these values:

All passwords (DB_PASS, MYSQL_ROOT_PASSWORD)
PayPal credentials (switch to live environment)
Invoice provider credentials
Disable simulation mode (FE_SIMULATE=false)

Never commit the .env file to version control. It’s already included in .gitignore.

Docker Compose Commands

Basic Operations

# Build and start in detached mode
docker-compose up -d --build

# View startup logs
docker-compose logs -f

Monitoring and Debugging

docker-compose ps

Database Management

Initial Setup

The database is automatically initialized when the db container first starts:

MySQL creates the computecnicos database
The init script at database/computecnicos_full.sql runs automatically
All tables, sample data, and indexes are created

Manual Database Operations

# Import from host machine
docker-compose exec -T db mysql -u root -proot_secret computecnicos < database/computecnicos_full.sql

Database Schema

The complete schema includes:

Core Tables: usuarios, productos, categorias, marcas, pedidos
Inventory: movimientos_inventario, proveedores
E-commerce: carrito, detalle_pedido, pedido_estados
Invoicing: facturas_electronicas, notas_credito
Reviews: resenas, resenas_imagenes, comentarios_producto
Authentication: password_resets, remember_tokens
Media: imagenes_producto

Volumes and Persistence

Persistent Volumes

CompuTécnicos uses Docker volumes to persist important data:

volumes:
  db_data:           # MySQL database files
  uploads_data:      # Product images and user uploads
  app_logs:          # Application logs

Volume Management

docker volume ls

File Permissions

The application requires specific permissions for uploads and logs:

docker-compose exec app chown -R www-data:www-data /var/www/html/uploads
docker-compose exec app chmod -R 775 /var/www/html/uploads

These permissions are automatically set during container build, but you may need to fix them if you manually copy files.

Production Deployment

Pre-Deployment Checklist

Before deploying to production:

Update Environment Variables

.env

# Use strong, unique passwords
DB_PASS=use_a_strong_random_password
MYSQL_ROOT_PASSWORD=use_another_strong_password

# Switch PayPal to live mode
PAYPAL_ENVIRONMENT=live

# Disable invoice simulation
FE_SIMULATE=false

# Use production ports if needed
APP_PORT=80

Disable Development Tools

Remove phpMyAdmin from production by not using the dev profile:

# Production start (without phpMyAdmin)
docker-compose up -d --build

Configure HTTPS

Set up a reverse proxy (Nginx or Traefik) to handle HTTPS:

nginx.conf

server {
    listen 80;
    server_name computecnicos.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name computecnicos.com;

    ssl_certificate /etc/letsencrypt/live/computecnicos.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/computecnicos.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable HTTPS Redirect

Uncomment the HTTPS redirect in .htaccess:

.htaccess

# Uncomment these lines for production:
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

Set Up Backups

Create automated backups:

backup.sh

#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
docker-compose exec db mysqldump -u root -proot_secret computecnicos | gzip > /backups/db_$DATE.sql.gz
docker cp computecnicos-app:/var/www/html/uploads /backups/uploads_$DATE

Deployment Commands

# On your server
git clone <repository-url> computecnicos
cd computecnicos

# Configure production environment
cp .env.example .env
nano .env  # Edit with production values

# Build and start
docker-compose up -d --build

# Verify
docker-compose ps
docker-compose logs -f app

Troubleshooting

Application Won’t Start

Check Docker Status

docker-compose ps

Look for containers with status other than “Up” or “healthy”.

View Container Logs

docker-compose logs app
docker-compose logs db

Look for error messages indicating the problem.

Verify Environment Variables

docker-compose config

This shows the resolved configuration with all environment variables.

Rebuild from Scratch

docker-compose down -v
docker-compose up -d --build --force-recreate

This deletes all data including the database. Only use for development.

Database Connection Issues

Connection Refused

Symptoms: Application shows “Connection refused” or can’t connect to database.Solutions:

Wait for database health check to complete:

docker-compose logs db | grep "ready for connections"

Verify database container is healthy:
```
docker-compose ps db
```
Check database credentials in .env match those in config/database.php

Access Denied

Symptoms: “Access denied for user” error.Solutions:

Verify environment variables:
```
docker-compose exec app env | grep DB_
```

Reset database with correct credentials:

docker-compose down -v
docker-compose up -d

Database Not Initialized

Symptoms: Tables don’t exist or schema is missing.Solutions:

Check if init script ran:

docker-compose logs db | grep "computecnicos_full.sql"

Manually import schema:

docker-compose exec -T db mysql -u root -proot_secret computecnicos < database/computecnicos_full.sql

Permission Issues

# Fix upload directory permissions
docker-compose exec app chown -R www-data:www-data /var/www/html/uploads
docker-compose exec app chmod -R 775 /var/www/html/uploads

Performance Issues

Slow Container Startup

Increase Docker Desktop memory allocation (Settings → Resources)
Use named volumes instead of bind mounts for better performance
On Windows, ensure WSL 2 backend is enabled

High Resource Usage

Limit MySQL memory usage in docker-compose.yml:

db:
  command: --max-connections=50 --key-buffer-size=16M

Enable PHP OPcache for better performance (already configured)

Port Conflicts

If ports are already in use:

.env

# Change ports in .env file
APP_PORT=8090
DB_PORT=3307
PMA_PORT=8082

Then restart:

docker-compose down
docker-compose up -d

Advanced Configuration

Custom PHP Configuration

Edit docker/php/custom.ini to customize PHP settings:

docker/php/custom.ini

upload_max_filesize = 32M
post_max_size = 32M
memory_limit = 256M
max_execution_time = 120
display_errors = Off
log_errors = On
error_log = /var/www/html/logs/php_errors.log

Rebuild after changes:

docker-compose up -d --build

MySQL Tuning

For production, tune MySQL performance in docker-compose.yml:

db:
  command: >
    --default-authentication-plugin=mysql_native_password
    --character-set-server=utf8mb4
    --collation-server=utf8mb4_unicode_ci
    --max-allowed-packet=64M
    --innodb-buffer-pool-size=1G
    --max-connections=100
    --query-cache-size=0

Health Checks

Add health checks to your docker-compose.yml:

app:
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost/status.php"]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 40s

Best Practices

Security

Use strong passwords in production
Disable phpMyAdmin in production
Enable HTTPS with valid certificates
Keep Docker images updated
Use secrets for sensitive data

Performance

Enable OPcache (already configured)
Use CDN for static assets
Implement database indexing
Monitor container resources
Use production PHP INI settings

Reliability

Set up automated backups
Use health checks
Implement log rotation
Monitor disk space
Test disaster recovery

Maintenance

Regular security updates
Monitor logs for errors
Clean up old volumes
Document configuration changes
Keep dependencies updated

Next Steps

Configuration Guide

Configure PayPal, invoicing, and other integrations

Production Setup

Learn about production deployment strategies

API Documentation

Explore available APIs and endpoints

Admin Guide

Learn how to manage your store

Get Started

Features

Configuration

Deployment

​Overview

​Architecture

​Services

​Environment Configuration

​Environment Variables

​Creating Your Configuration

​Docker Compose Commands

​Basic Operations

​Monitoring and Debugging

​Database Management

​Initial Setup

​Manual Database Operations

​Database Schema

​Volumes and Persistence

​Persistent Volumes

​Volume Management

​File Permissions

​Production Deployment

​Pre-Deployment Checklist

​Deployment Commands

​Troubleshooting

​Application Won’t Start

​Database Connection Issues

​Permission Issues

​Performance Issues

​Port Conflicts

​Advanced Configuration

​Custom PHP Configuration

​MySQL Tuning

​Health Checks

​Best Practices

Security

Performance

Reliability

Maintenance

​Next Steps

Configuration Guide

Production Setup

API Documentation

Admin Guide

Build docs developers (and LLMs) love

Overview

Architecture

Services

Environment Configuration

Environment Variables

Creating Your Configuration

Docker Compose Commands

Basic Operations

Monitoring and Debugging

Database Management

Initial Setup

Manual Database Operations

Database Schema

Volumes and Persistence

Persistent Volumes

Volume Management

File Permissions

Production Deployment

Pre-Deployment Checklist

Deployment Commands

Troubleshooting

Application Won’t Start

Database Connection Issues

Permission Issues

Performance Issues

Port Conflicts

Advanced Configuration

Custom PHP Configuration

MySQL Tuning

Health Checks

Best Practices

Next Steps