📚 2. System Requirements for Ultimate Image Optimizer

Before proceeding with the installation, it is crucial to ensure your server environment is correctly configured for the JaJuMa Ultimate Image Optimizer for Magento 2. A few minutes spent on this pre-flight check can prevent common issues and ensure a smooth setup process, allowing you to leverage all the features described in our documentation.

2.1 📋 Pre-Installation Checklist

Use this table to quickly confirm your environment is ready. This checklist ensures that the extension has the necessary foundation to perform all optimization tasks effectively.

2.2 🔧 Verifying Server-Side Conversion Tools

The extension's core function is converting images to modern formats. This requires specific tools to be installed on your server. For each format (WebP/AVIF), at least one of the supported conversion tools must be installed and operational.

This Extension supports three tools for WebP image conversion:

• GD
• cwebp
• Imagemagick

And four different tools for AVIF image conversion:

• avifenc
• cavif
• Imagemagick
• GD

💡 Pro Tip: For the best balance of speed, quality, and ease of setup, we strongly recommend using cwebp for WebP and cavif for AVIF. The cavif tool is conveniently bundled with the extension.

The following sections guide you through verifying these tools using the Command Line Interface (CLI), which is ideal for checking requirements before installation.

2.2.1 Verifying WebP Conversion Tools

GD Library (WebP)

The GD library is often included with PHP.

• How to Check:

  php -i | grep "WebP Support"

• Expected Result:
  The output must include WebP Support => enabled. If it's disabled or absent, you must use one of the other tools.

⚠️ Warning: Your PHP Command Line Interface (CLI) might use a different php.ini configuration file than your web server. If GD WebP support is enabled for your website but not showing in the CLI, this is a likely cause.

cwebp (Recommended for WebP)

cwebp is Google's official tool and provides the best results for WebP conversion.

• How to Check:

  # Check for global command
  cwebp
  
  # If not found globally, check the bundled binary
  # Path for manual install
  ./app/code/Jajuma/ImageOptimizerUltimate/bin/cwebp
  
  # Path for composer install
  ./vendor/jajuma/module-imageoptimizerultimate/bin/cwebp

• Expected Result:
  The command should display its help/manual page. If you see command not found for the global check, use the direct path to the bundled binary. If the direct path gives a Permission denied error, make it executable with chmod +x <path_to_cwebp>.

Please Note: For cwebp to work correctly with the extension, cwebp and all dependencies need to be installed correctly on your system. If needed, please check with your hosting provider to get cwebp up and running and to ensure these requirements are met.

ImageMagick (WebP)

You can also use ImageMagick for WebP conversion.

• How to Check:

  convert -v | grep 'delegates' | grep 'webp'

• Expected Result:
  The output should contain the delegate webp. If not, your ImageMagick installation does not support WebP.

2.2.2 Verifying AVIF Conversion Tools

cavif (Recommended for AVIF)

cavif is an efficient AVIF encoder that is bundled with the extension.

• How to Check:

  # Path for manual install
  ./app/code/Jajuma/ImageOptimizerUltimate/bin/cavif
  
  # Path for composer install
  ./vendor/jajuma/module-imageoptimizerultimate/bin/cavif

• Expected Result:
  The command should output Please specify image paths to convert. If you see Permission denied, ensure the file is executable (chmod +x cavif).

GD Library (AVIF)

AVIF support in GD is newer and has specific requirements.

• How to Check:

  php -i | grep "AVIF Support"

• Expected Result:
  The output must show AVIF Support => enabled. This requires PHP 8.1+ with the GD library compiled with AVIF support. For further instructions, see the official PHP documentation here.

ImageMagick (AVIF)

⚠️ Warning: To support AVIF, your ImageMagick installation must be version 7.0.10-25 or newer. Older versions will not work for AVIF conversion.

• How to Check:

  convert -v | grep 'Version'

• Expected Result:
  The output will show the installed ImageMagick version. Confirm it meets the minimum version requirement.

avifenc

avifenc is another powerful AVIF encoder, but typically requires manual installation.

• How to Check:

  avifenc

• Expected Result:
  The command displays its help/manual page. If you see command not found, you will need to install it or use a different tool like cavif.

2.3 💻 Verification via Magento Admin (Post-Installation)

If you have already installed the extension, these methods are the fastest way to confirm that your server tools are correctly configured and accessible by the extension.

2.3.1 Using the Test & Preview Conversion Tool

This is the most direct way to confirm a specific tool is working.

1. Navigate to JaJuMa > Image Optimization Configuration > Performance.
2. Open either the WebP Conversion Configurations or AVIF Conversion Configurations section.
3. Select a tool, enter a valid Product ID, and click Test Conversion Tool.
   • Success: A popup appears showing a side-by-side comparison of the original and converted image.
   • Failure: A popup appears with an error message, indicating a problem with the tool.

2.3.2 Using the Built-in Configuration Checker

This tool provides a broader overview of your entire setup.

1. Navigate to JaJuMa > Image Optimization Configuration > General > Debug.
2. Click the Check Configuration button.
3. In the popup, click Validate WebP Conversion Tools and Validate AVIF Conversion Tools for a live check of all supported tools.

2.4 🤔 Troubleshooting & FAQ

Why does a tool work on my website but fail in the CLI?

This is a common issue caused by different PHP configurations. Your web server (e.g., Apache, Nginx) can have one php.ini file with certain extensions enabled, while the command-line PHP uses a separate php.ini. You must ensure the required tools/extensions are enabled in both environments, or rely on binary tools like cwebp and cavif which do not depend on PHP extensions.

What if I don't have command-line (CLI) access?

If you don't have CLI access, you must rely on the post-installation verification methods within the Magento Admin. Start by installing the extension, then use the Check Configuration and Test Conversion Tool buttons to diagnose your server's capabilities.

My hosting provider says a tool is installed, but it's not working. What now?

1. Check the Path: The tool might be installed in a non-standard location. Ask your provider for the absolute path to the executable (e.g., /usr/local/bin/cwebp). You can enter this path directly in the extension's configuration.
2. Check Permissions: The web server user (e.g., www-data, apache) needs permission to execute the tool's binary file. Your hosting provider may need to adjust these permissions.
3. Check for Dependencies: Some tools have other system libraries they depend on. An error message in the logs or from the Test Conversion Tool can often point to a missing dependency.

📞 Need Help?

Having trouble with the setup? Check our Troubleshooting, FAQ & Best Practices for common solutions.

Still have questions or need help verifying your system requirements? Our expert team is here to assist. Please don't hesitate to contact our support team for personalized assistance.