Skip to main content

​
System Requirements

OpenCart 4.x requires:
  • PHP 8.0+ with extensions: curl, gd, zip, mysqli, openssl, zlib
  • MySQL 5.7+ or MariaDB 10.3+ (or compatible database)
  • Web Server: Apache 2.4+ or Nginx 1.18+
  • Composer for dependency management
OpenCart includes a Docker development environment using Docker Compose.

​
Initial Setup

1

Initialize Environment

Copy the example environment configuration:
make init
This creates docker/.env.docker from the example template.
2

Build Images

Build the PHP, Apache, and MySQL Docker images:
make build
3

Start Services

Launch the development stack:
make up
To include optional services like Redis:
make up profiles="redis"
4

Install OpenCart

Visit http://localhost in your browser and complete the web installer:
  1. Accept the license agreement
  2. Pre-installation check passes automatically
  3. Configure database connection (default credentials in docker/.env.docker)
  4. Set up admin account
  5. Complete installation
After installation, delete the install directory:
rm -rf upload/install/

​
Docker Commands

CommandDescription
make upStart all services
make downStop and remove containers
make phpOpen shell in PHP container as www-data
make logsTail all service logs
make restartRestart all services
make buildRebuild Docker images

​
Accessing the PHP Container

To run CLI commands inside the PHP container: 
make php
This opens a shell as the www-data user. From here you can: 
# Run Composer commands
composer install

# Run code quality tools
php tools/phpstan.phar analyze

# Access the OpenCart directory
cd /var/www/html/upload/

​
Native Installation

For custom setups without Docker:

​
Install PHP Dependencies

From the repository root: 
composer install --no-interaction
This installs libraries into upload/system/storage/vendor/ as configured in composer.json.

​
Web Server Configuration

​
Apache

Point your virtual host to the upload/ directory: 
<VirtualHost *:80>
    ServerName opencart.local
    DocumentRoot /path/to/opencart/upload
    
    <Directory /path/to/opencart/upload>
        AllowOverride All
        Require all granted
        DirectoryIndex index.php
    </Directory>
    
    ErrorLog ${APACHE_LOG_DIR}/opencart-error.log
    CustomLog ${APACHE_LOG_DIR}/opencart-access.log combined
</VirtualHost>
Enable required modules: 
a2enmod rewrite
systemctl restart apache2

​
Nginx

server {
    listen 80;
    server_name opencart.local;
    root /path/to/opencart/upload;
    
    index index.php;
    
    location / {
        try_files $uri $uri/ /index.php?$args;
    }
    
    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php8.0-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
    
    location ~ /\.ht {
        deny all;
    }
}

​
Database Setup

Create a MySQL database and user: 
CREATE DATABASE opencart CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'opencart'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON opencart.* TO 'opencart'@'localhost';
FLUSH PRIVILEGES;

​
File Permissions

Ensure the web server can write to required directories: 
chmod 755 upload/
chmod 644 upload/config.php
chmod 644 upload/admin/config.php
chmod -R 755 upload/system/storage/
chmod -R 755 upload/image/
chmod -R 755 upload/download/

​
Development Tools

​
Code Quality Checks

Run these checks before committing (same as CI): 
find upload -type f -name "*.php" ! -path 'upload/system/storage/vendor/*' -exec php -l -n {} +

​
IDE Configuration

​
PHPStorm / IntelliJ IDEA

  1. PHP Language Level: Set to PHP 8.0 or 8.1
  2. Namespaces: Mark upload/ as source root
  3. Code Style: Import .php-cs-fixer.php settings
  4. Database: Connect to your development database for code completion

​
VS Code

Install recommended extensions:
  • PHP Intelephense
  • PHP Debug (with Xdebug)
  • EditorConfig for VS Code
Create .vscode/settings.json: 
{
    "php.suggest.basic": false,
    "php.validate.enable": false,
    "intelephense.environment.phpVersion": "8.0.0"
}

​
Debugging

​
Xdebug with Docker

Add to docker/.env.docker: 
XDEBUG_MODE=develop,debug
XDEBUG_CONFIG=client_host=host.docker.internal
Rebuild containers: 
make down
make build
make up

​
Xdebug with Native PHP

Install Xdebug extension: 
pecl install xdebug
Add to php.ini: 
[xdebug]
zend_extension=xdebug.so
xdebug.mode=develop,debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.start_with_request=yes

​
Configuration Files

After installation, OpenCart creates two config files: 
<?php
// HTTP
define('HTTP_SERVER', 'http://localhost/');

// HTTPS
define('HTTPS_SERVER', 'http://localhost/');

// DIR
define('DIR_OPENCART', '/var/www/html/upload/');
define('DIR_APPLICATION', DIR_OPENCART . 'catalog/');
define('DIR_EXTENSION', DIR_OPENCART . 'extension/');
define('DIR_IMAGE', DIR_OPENCART . 'image/');
define('DIR_SYSTEM', DIR_OPENCART . 'system/');
define('DIR_STORAGE', DIR_SYSTEM . 'storage/');
define('DIR_LANGUAGE', DIR_APPLICATION . 'language/');
define('DIR_TEMPLATE', DIR_APPLICATION . 'view/template/');
define('DIR_CONFIG', DIR_SYSTEM . 'config/');
define('DIR_CACHE', DIR_STORAGE . 'cache/');
define('DIR_DOWNLOAD', DIR_OPENCART . 'download/');
define('DIR_LOGS', DIR_STORAGE . 'logs/');
define('DIR_SESSION', DIR_STORAGE . 'session/');
define('DIR_UPLOAD', DIR_STORAGE . 'upload/');

// DB
define('DB_DRIVER', 'mysqli');
define('DB_HOSTNAME', 'mysql');
define('DB_USERNAME', 'opencart');
define('DB_PASSWORD', 'opencart');
define('DB_DATABASE', 'opencart');
define('DB_PORT', '3306');
define('DB_PREFIX', 'oc_');
Never commit config.php or admin/config.php to version control. These files contain environment-specific settings and database credentials.

​
Next Steps

Architecture

Understand OpenCart’s architecture

Coding Standards

Follow coding conventions

MVC Pattern

Learn the MVC pattern

Routing

Understand routing system

Build docs developers (and LLMs) love

Get started for freeTalk to us