Installation Guide
Complete guide for installing the OpenCart 3 to 4 Migration Tool.
Table of contents
- Prerequisites
- Method 1: Web Installation (Recommended)
- Method 2: Manual Installation
- Method 3: Docker Installation
- Post-Installation
- Environment-Specific Setup
- Troubleshooting Installation
- Next Steps
- Need Help?
Prerequisites
System Requirements
- PHP: 7.4 or higher (8.0+ recommended)
- MySQL: 5.7+ or MariaDB 10.2+
- Memory: 512MB minimum (1GB recommended)
- Disk Space: Sufficient for database + images
PHP Extensions
Required extensions:
- PDO & PDO_MySQL
- SQLite3
- GD or Imagick
- JSON
- mbstring
- OpenSSL
OpenCart Installations
- OpenCart 3.x - Fully installed and configured
- OpenCart 4.x - Fresh installation with default data installed
The target OpenCart 4 must have default data (languages, currencies, zones) installed. Complete the OpenCart 4 installation wizard first. The migration tool requires this default data for ID mapping.
Method 1: Web Installation (Recommended)
Step 1: Clone Repository
# Clone to your web server directory
cd /var/www/html/
git clone https://github.com/kunwar-shah/opencart-migration-tool.git
cd opencart-migration-tool
Step 2: Configure Permissions
# Linux/Unix
chmod -R 755 storage/ logs/
chown -R www-data:www-data .
# Windows (using icacls)
icacls storage /grant Users:F /T
icacls logs /grant Users:F /T
Step 3: Configure Database
# Copy example configuration
cp config/config.example.php config/config.php
# Edit configuration
nano config/config.php
Minimum configuration:
'database' => [
'source' => [
'host' => 'localhost',
'database' => 'opencart3_db',
'username' => 'db_user',
'password' => 'db_password',
'table_prefix' => 'oc_'
],
'target' => [
'host' => 'localhost',
'database' => 'opencart4_db',
'username' => 'db_user',
'password' => 'db_password',
'table_prefix' => 'oc_'
]
],
'images' => [
'source_path' => '/path/to/opencart3/image',
'target_path' => '/path/to/opencart4/image',
],
Step 4: Run Web Installer
- Navigate to:
http://your-domain.com/install.php - Installer checks all requirements
- Click “Start Installation”
- Default credentials created:
admin / test123
Change the default password immediately after first login!
Step 5: Verify Installation
- Login at:
http://your-domain.com/ - Dashboard loads successfully
- All migration steps visible
- No errors in logs
Method 2: Manual Installation
For advanced users or automated deployments.
Database Setup
-- Optional: Create separate tracking database
CREATE DATABASE migration_tracking;
GRANT ALL PRIVILEGES ON migration_tracking.* TO 'migration_user'@'localhost';
FLUSH PRIVILEGES;
Initialize Schema
# Run database initialization
php database/init.php
Configure Web Server
Apache (.htaccess included)
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ public/index.php [QSA,L]
</IfModule>
Nginx
server {
listen 80;
server_name migration.example.com;
root /var/www/opencart-migration-tool/public;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
Method 3: Docker Installation
Using Docker Compose
# docker-compose.yml
version: '3.8'
services:
migration-tool:
image: php:7.4-apache
ports:
- "8080:80"
volumes:
- ./:/var/www/html
environment:
- PHP_MEMORY_LIMIT=512M
depends_on:
- mysql
mysql:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: migration_tracking
ports:
- "3306:3306"
volumes:
- mysql_data:/var/lib/mysql
volumes:
mysql_data:
# Start containers
docker-compose up -d
# Access tool
http://localhost:8080/install.php
Post-Installation
Security Hardening
# Remove installation script
rm install.php
# Restrict config permissions
chmod 400 config/config.php
# Protect logs directory
cat > logs/.htaccess << EOF
Order deny,allow
Deny from all
EOF
Test Connections
# Verify database connections
php migrate.php test-connections
# Expected output:
✓ Source database: OK
✓ Target database: OK
✓ Tracking database: OK
Backup Databases
Always backup before migration!
# Backup OpenCart 3
mysqldump -u root -p opencart3_db > oc3_backup.sql
# Backup OpenCart 4
mysqldump -u root -p opencart4_db > oc4_backup.sql
Environment-Specific Setup
XAMPP/WAMP/MAMP
# 1. Extract to htdocs/www
cd C:/xampp/htdocs
git clone https://github.com/kunwar-shah/opencart-migration-tool.git
# 2. Configure virtual host (optional)
# Edit: C:/xampp/apache/conf/extra/httpd-vhosts.conf
<VirtualHost *:80>
ServerName migration.local
DocumentRoot "C:/xampp/htdocs/opencart-migration-tool/public"
<Directory "C:/xampp/htdocs/opencart-migration-tool/public">
AllowOverride All
Require all granted
</Directory>
</VirtualHost>
# 3. Update hosts file
# C:\Windows\System32\drivers\etc\hosts
127.0.0.1 migration.local
# 4. Restart Apache
# Access: http://migration.local/install.php
Troubleshooting Installation
“Database connection failed”
# Test connection manually
mysql -u username -p -h localhost database_name
# Check credentials in config/config.php
“Permission denied” errors
# Fix ownership
sudo chown -R www-data:www-data /path/to/tool
# Fix permissions
sudo chmod -R 755 storage/ logs/
“PHP extension missing”
# Ubuntu/Debian
sudo apt-get install php7.4-mysql php7.4-sqlite3 php7.4-gd
# CentOS/RHEL
sudo yum install php74-mysql php74-pdo php74-gd
# Restart web server
sudo systemctl restart apache2
Next Steps
- ✅ Installation complete
- Read Configuration Guide
- Review Features Documentation
- Start with Default Data migration
- Follow dashboard workflow