JaJuMa Magento & Hyvä Extension Installation Guide

Installing Magento 2 extensions is essential to expand the functionality and enhance your eCommerce store. This comprehensive guide walks you through various methods to install JaJuMa Magento 2 extensions, including via Composer (recommended) and manual FTP/SSH. We'll also cover crucial preparation steps and common pitfalls to help you ensure a smooth installation process.

While this guide is tailored for JaJuMa extensions, many principles apply to installing other Magento 2 modules.


🔧 Preparation: Essential Steps Before Installing Magento 2 Extensions

Before you begin installing any Magento 2 module, it's crucial to prepare your environment properly to prevent potential issues and data loss.

1. Check System and Extension Compatibility

  • Magento Version: Ensure the extension is compatible with your Magento 2 version. You can usually find this information on the extension's product page or in its composer.json file.
  • PHP Version: Verify that your server's PHP version meets the extension's requirements.
  • Module Conflicts: Be aware that other third-party extensions might conflict. While JaJuMa extensions are built to Magento standards, complex environments can sometimes lead to unforeseen interactions. If possible, check for known incompatibilities.

✅ 2. Create a Staging Environment

Always duplicate your live store onto a staging or development server. Perform the installation and thorough testing there first. This allows you to identify and resolve any issues without affecting your live customers or sales.

🔒 3. Backup Your Magento Store

Before making any changes, create a full backup of your Magento store, including:

  • Magento core files
  • Database
  • Themes and extensions

⚠️ Warning: Never skip backups, especially when working on a live server. Backups are your safety net, essential for recovering from failed installations or unexpected compatibility problems.


📁 Method 1: Manual Installation via FTP or SSH

Manual installation is a straightforward option if you prefer working directly with your server files. SSH is generally recommended over FTP for better security and reliable command-line access.

🔻 Step-by-Step Instructions:

  1. Download the extension as a .zip file from your JaJuMa Customer Account.

  2. Connect to Your Server: Use an FTP/SFTP client (e.g., FileZilla, WinSCP) or SSH to access your server.

  3. Create the Module Directory: In your Magento installation root, navigate to the app/code/ directory. Create the necessary vendor and module folders. The path will be app/code/Jajuma/[ExtensionName]. For example, if the extension name is ImageOptimizerUltimate, you would create:

    # Example: /app/code/Jajuma/ImageOptimizerUltimate
    mkdir -p app/code/Jajuma/[ExtensionName]

    Tip: You can find the correct [ExtensionName] (e.g., ImageOptimizerUltimate, SpeedOptimizer) in the registration.php file included within the extension package. It will look like Jajuma_[ExtensionName].

  4. Upload and Extract Files: Upload the downloaded .zip file to a temporary location on your server (e.g., /tmp/) or directly to the app/code/Jajuma/[ExtensionName] directory if your server setup allows. Then, extract its contents into the app/code/Jajuma/[ExtensionName] directory. Ensure the file structure matches the module's intended layout (e.g., app/code/Jajuma/[ExtensionName]/etc/module.xml).

  5. Set File Permissions (Crucial): Incorrect file permissions are a common cause of issues. Ensure the web server user (e.g., www-data, apache) has appropriate read (and sometimes write) access to the module files and directories. Consult Magento's official documentation for recommended permissions. Typically, directories should be 755 and files 644.

  6. Run Magento CLI Commands: From your Magento root directory, execute the following commands in order via SSH:

    # Disable caches (optional, but can prevent issues during upgrade)
    # php bin/magento cache:disable
    
    # Enable the module (if it's a new module or was previously disabled)
    php bin/magento module:enable Jajuma_[ExtensionName]
    
    # Run setup upgrade to install/update database schemas and data
    php bin/magento setup:upgrade
    
    # Compile dependency injection (required for production mode, good practice for developer mode)
    php bin/magento setup:di:compile
    
    # Deploy static content (the -f flag forces deployment)
    php bin/magento setup:static-content:deploy -f
    # Add your active locales if needed, e.g., en_US de_DE fr_FR
    
    # Flush Magento caches
    php bin/magento cache:flush

    If you disabled caches earlier, re-enable them:

    # php bin/magento cache:enable

🧩 Common Pitfalls with Manual Installation:

  • Incorrect Upload Path: Double-check that files are uploaded to the correct app/code/Jajuma/[ExtensionName] directory. An incorrect path will prevent Magento from recognizing the module.
  • Forgetting setup:upgrade: This command is crucial as it registers the module with Magento, installs any necessary database schemas, and runs setup scripts. Skipping it will lead to a non-functional or broken extension.
  • File Permissions Issues: After uploading files (especially via FTP, which can sometimes alter permissions), the web server user might not have the necessary read/execute permissions for the module's files and directories. This can lead to errors or a non-functional site.
  • Not Clearing Caches Thoroughly: Magento relies heavily on caching. Always flush all relevant caches (config, layout, block_html, full_page, etc.) after installation or significant changes. The cache:flush command is generally sufficient, but sometimes cache:clean for specific types might be needed.
  • Compilation Errors (setup:di:compile): If you're running in production mode (or even developer mode), setup:di:compile is essential. Errors during compilation often point to PHP syntax errors in the module, compatibility issues with your PHP version, or incorrect module structure. Check your system logs (var/log/system.log, var/log/exception.log) for details.
  • Static Content Deployment Issues: If setup:static-content:deploy fails or doesn't complete, it can lead to missing styles or JavaScript on the frontend and backend. Ensure you have enough memory and correct file permissions for the pub/static and var/view_preprocessed directories.

📦 Method 2: Installation via Composer (Recommended)

Using Composer is the highly recommended method for installing Magento 2 extensions. It simplifies the process, manages dependencies automatically, facilitates easier updates, and aligns with Magento's standard practices.

Why Choose Composer?

  • Dependency Management: Composer automatically handles any libraries or other modules the extension depends on, ensuring all necessary components are present.
  • Easy Updates: Updating the extension to a new version is typically a single Composer command.
  • Magento Standard: It's the official and preferred way to manage Magento components and third-party modules.
  • Version Control: Composer helps manage specific versions of extensions, ensuring stability and predictability in your Magento environment.
  • Autoloading: Composer handles the autoloading of classes, making module integration seamless.

🛍 a) Installation from Magento Marketplace

If you acquired the JaJuMa extension through the Adobe Commerce Marketplace (formerly Magento Marketplace):

  1. Configure auth.json: Ensure your Magento project's auth.json file (usually in the Magento root directory) contains your Marketplace authentication keys (public and private keys). You can find these in your Marketplace account under "My Profile" > "Access Keys". If auth.json doesn't exist, you might need to create it.
  2. Follow the official Magento Composer Installation Guide for detailed steps on configuring Marketplace authentication.
  3. Require the Extension: Open your terminal or command prompt, navigate to your Magento root directory, and run:

    # Replace 'jajuma/module-packagename' with the actual Composer package name
    # (e.g., jajuma/module-imageoptimizerultimate). You can find this on the Marketplace product page.
    composer require jajuma/module-packagename

    Note: Make sure the Marketplace account associated with your auth.json keys has "purchased" (even if it's a free extension) or has active access to the extension.

  4. Run Magento CLI Commands:
    php bin/magento setup:upgrade
    php bin/magento setup:di:compile # If in production mode, or for good measure
    php bin/magento setup:static-content:deploy -f # Add your active locales if needed
    php bin/magento cache:flush

🗇 b) Installation of Free Extensions from GitHub

For JaJuMa's free extensions available on GitHub:

  1. Require the Extension: In your Magento root directory, run the composer command specific to the module. The package name will be in the format jajuma/module-modulename.
    # Replace 'jajuma/module-example' with the specific module's GitHub package name
    # (e.g., jajuma/module-powertoys)
    composer require jajuma/module-example

    You can find our free modules and their respective Composer package names at JaJuMa - Free Magento & Hyvä Extensions.

  2. Run Magento CLI Commands:
    php bin/magento setup:upgrade
    php bin/magento setup:di:compile # If in production mode
    php bin/magento setup:static-content:deploy -f # Add your active locales if needed
    php bin/magento cache:flush

💼 c) Installation After Purchase from jajuma.de

If you purchased an extension directly from the JaJuMa website (jajuma.de), you'll typically receive a .zip package. You have a few Composer-based options to install it:

  • Option 1 – Install via Local path Repository (Recommended for direct downloads if not using artifacts)

    This method involves telling Composer to look for the package in a local directory.

    1. Download and Extract: Download the .zip file from your JaJuMa customer account and extract it. You should have a directory structure like Jajuma/[ExtensionName].
    2. Place the Module: Copy the extracted Jajuma directory (which contains the [ExtensionName] sub-directory with the module's code) into your Magento project's app/code/ directory. So the final path will be app/code/Jajuma/[ExtensionName].
    3. Modify composer.json (if not already set up for app/code): Ensure your main composer.json in the Magento root includes a path repository that scans app/code/*/* or specifically for the module. Many Magento setups already scan app/code. If not, add or modify the repositories section in your root composer.json:
      "repositories": [
          // ... other repositories ...
          {
              "type": "path",
              "url": "app/code/*/*",
              "options": {
                  "symlink": true
              }
          }
          // Or more specifically (less common for app/code):
          // {
          //     "type": "path",
          //     "url": "app/code/Jajuma/ExtensionName" // Replace ExtensionName
          // }
      ],

      The "symlink": true option is often recommended for path repositories to avoid copying files into the vendor directory.

    4. Require the Extension: Identify the Composer package name from the extension's own composer.json file (located within app/code/Jajuma/[ExtensionName]/composer.json). It will be in the format jajuma/module-extensionname.
      # Replace 'jajuma/module-extensionname' with the actual Composer name
      # and optionally specify a version constraint like ":*" or the specific version.
      composer require jajuma/module-extensionname:"*"
      php bin/magento setup:upgrade
      php bin/magento setup:di:compile
      php bin/magento setup:static-content:deploy -f
      php bin/magento cache:flush
  • Option 2 – Install via Local Artifact Repository (Good for managing .zip packages with Composer)

    This method uses Composer's artifact repository type to install directly from the .zip file without extracting it into app/code first.

    1. Download the Package: Download the .zip file from your JaJuMa customer account.
    2. Create an Artifacts Directory: Create a directory within your Magento project (or elsewhere accessible by Composer) to store these zip packages, e.g., composer-packages/ or artifacts/. Place the downloaded Jajuma-[ExtensionName]-version.zip file into this directory.
    3. Configure composer.json: Add an artifact repository to your Magento project's root composer.json:
      "repositories": [
          // ... other repositories ...
          {
              "type": "artifact",
              "url": "composer-packages/" // Path to your artifacts directory relative to composer.json
          }
      ],
    4. Require the Extension: The package name and version are usually found in the extension's composer.json file (inside the zip) or might be part of the zip filename.
      # Replace 'jajuma/module-extensionname' with the actual Composer name
      # and ':version' with the specific version of the package (e.g., :1.0.0).
      composer require jajuma/module-extensionname:1.0.0
      php bin/magento setup:upgrade
      php bin/magento setup:di:compile
      php bin/magento setup:static-content:deploy -f
      php bin/magento cache:flush
  • Option 3 – Install via Private Git Repository (For advanced users managing code with Git)

    If you prefer to manage the extension code in your own private Git repository (e.g., GitHub, GitLab, Bitbucket):

    1. Push to Private Repo: Download and extract the extension. Initialize a git repository within the root directory of the extracted extension code (e.g., the directory containing Jajuma/[ExtensionName], or directly within [ExtensionName] if you adjust paths accordingly) and push it to your private Git hosting service.
    2. Add Repository to composer.json: Add your private repository to your Magento project's root composer.json:
      "repositories": [
          // ... other repositories ...
          {
              "type": "vcs",
              "url": "git@github.com:YourUsername/YourPrivateRepoName.git" // Replace with your Git SSH or HTTPS URL
          }
      ],

      Ensure Composer has the necessary credentials (e.g., SSH keys for SSH URLs) to access your private repository.

    3. Require the Extension: Use the Composer package name found in the extension's composer.json.
      # Replace 'jajuma/module-extensionname' with the Composer name
      # and specify a branch (e.g., dev-main) or tag (e.g., 1.0.0) from your private repo.
      composer require jajuma/module-extensionname:dev-main
      php bin/magento setup:upgrade
      php bin/magento setup:di:compile
      php bin/magento setup:static-content:deploy -f
      php bin/magento cache:flush

📌 Post-Installation: Verification and Final Steps

After successfully running the installation commands, follow these final steps and tips:

  • Clear Magento Caches Thoroughly: Beyond php bin/magento cache:flush, if you encounter unexpected issues, consider cleaning specific cache types or even manually clearing the var/cache/ and var/page_cache/ directories (on a staging environment first!):
    # More specific cache cleaning if needed
    php bin/magento cache:clean config layout block_html full_page translate
    # Then flush all
    php bin/magento cache:flush
  • Production Mode: For live sites, always ensure Magento is in production mode for optimal performance and security. If you were in developer or default mode for installation, switch back:
    php bin/magento deploy:mode:set production

    This command will also trigger DI compilation and static content deployment if needed.

  • 🔎 Verify Functionality: Thoroughly test the extension's features on your staging environment. Check both frontend and backend functionality to ensure it works as expected with your specific theme, Magento version, and other installed modules.
  • Avoid Direct Live Store Installation (Initially): Reiterating this crucial point – always test on a staging/development environment first before deploying to your live store.
  • Check Extension Compatibility (Recap): If you skipped this in preparation, double-check PHP and Magento version compatibility now.
  • 🔍 Troubleshooting Composer Errors:
    • Could not find a matching version of package jajuma/[module-name]:
      • Marketplace: This often means the authentication key for the Magento Marketplace repository (repo.magento.com) in your auth.json is incorrect, invalid, or the account doesn't have access to the purchased module. Verify your auth.json keys and ensure the extension is associated with that Marketplace account.
      • Direct Purchase (Artifact/Path): Ensure the package name and version constraint in your composer require command are correct and exactly match the details in the extension's composer.json file. For artifact repositories, ensure the zip file is correctly placed and named. For path repositories, ensure the path in your root composer.json is correct and the module files are in the specified location.
    • Memory Issues: Composer can be memory-intensive, especially on large Magento projects. If you encounter "Allowed memory size of X bytes exhausted" errors, try running Composer with an increased PHP memory limit:
      php -d memory_limit=-1 $(which composer) require ...
      # or for Windows:
      # php -d memory_limit=-1 C:\path\to\composer.phar require ...
  • 📄 Module-Specific Documentation: Always refer to the specific JaJuMa extension's documentation (often a docs.md or PDF manual included with the extension or on its product page) for any additional configuration or post-installation steps unique to that module.
  • 🤝 Extension Conflicts: If you experience unexpected behavior after installation (e.g., broken functionality, errors), it might be due to a conflict with another third-party extension. On your staging site, try disabling other recently installed or potentially conflicting modules one by one to isolate the issue. Check Magento logs (var/log/) and browser console for error messages.

💡 Need Help with Your JaJuMa Extension Installation?

If you encounter any difficulties during the installation process or have further questions specific to a JaJuMa extension, please don't hesitate to contact JaJuMa. We're happy to assist you in getting your Magento 2 store enhanced with our extensions. Please provide as much detail as possible, including your Magento version, PHP version, the extension name and version, and any error messages you're seeing.

Do you find all information about us and our services?

thumb-up
thumb-down