Do you find all information about us and our services?
Extensions by Category
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:
-
Download the extension as a
.zip
file from your JaJuMa Customer Account. -
Connect to Your Server: Use an FTP/SFTP client (e.g., FileZilla, WinSCP) or SSH to access your server.
-
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 beapp/code/Jajuma/[ExtensionName]
. For example, if the extension name isImageOptimizerUltimate
, 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 theregistration.php
file included within the extension package. It will look likeJajuma_[ExtensionName]
. -
Upload and Extract Files: Upload the downloaded
.zip
file to a temporary location on your server (e.g.,/tmp/
) or directly to theapp/code/Jajuma/[ExtensionName]
directory if your server setup allows. Then, extract its contents into theapp/code/Jajuma/[ExtensionName]
directory. Ensure the file structure matches the module's intended layout (e.g.,app/code/Jajuma/[ExtensionName]/etc/module.xml
). -
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 be755
and files644
. -
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. Thecache:flush
command is generally sufficient, but sometimescache: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 thepub/static
andvar/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):
- Configure
auth.json
: Ensure your Magento project'sauth.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". Ifauth.json
doesn't exist, you might need to create it. - Follow the official Magento Composer Installation Guide for detailed steps on configuring Marketplace authentication.
-
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. - 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:
- 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.
- 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.
- Download and Extract: Download the
.zip
file from your JaJuMa customer account and extract it. You should have a directory structure likeJajuma/[ExtensionName]
. - Place the Module: Copy the extracted
Jajuma
directory (which contains the[ExtensionName]
sub-directory with the module's code) into your Magento project'sapp/code/
directory. So the final path will beapp/code/Jajuma/[ExtensionName]
. - Modify
composer.json
(if not already set up forapp/code
): Ensure your maincomposer.json
in the Magento root includes apath
repository that scansapp/code/*/*
or specifically for the module. Many Magento setups already scanapp/code
. If not, add or modify therepositories
section in your rootcomposer.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 thevendor
directory. - Require the Extension:
Identify the Composer package name from the extension's own
composer.json
file (located withinapp/code/Jajuma/[ExtensionName]/composer.json
). It will be in the formatjajuma/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
- Download and Extract: Download the
-
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 intoapp/code
first.- Download the Package: Download the
.zip
file from your JaJuMa customer account. - 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/
orartifacts/
. Place the downloadedJajuma-[ExtensionName]-version.zip
file into this directory. - Configure
composer.json
: Add an artifact repository to your Magento project's rootcomposer.json
:"repositories": [ // ... other repositories ... { "type": "artifact", "url": "composer-packages/" // Path to your artifacts directory relative to composer.json } ],
- 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
- Download the Package: Download the
-
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):
- 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. - Add Repository to
composer.json
: Add your private repository to your Magento project's rootcomposer.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.
- 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
- 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
📌 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 thevar/cache/
andvar/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 yourauth.json
is incorrect, invalid, or the account doesn't have access to the purchased module. Verify yourauth.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'scomposer.json
file. For artifact repositories, ensure the zip file is correctly placed and named. For path repositories, ensure the path in your rootcomposer.json
is correct and the module files are in the specified location.
- Marketplace: This often means the authentication key for the Magento Marketplace repository (
- 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.