How to Install Magento 2 on Windows WSL

|

,

|

The tutorial guides students and new users on installing the Magento eCommerce platform on Windows 10 WSL 2 using the Nginx HTTP server on Ubuntu 20.04. Key steps include enabling WSL and the virtual machine platform in Windows, installing Ubuntu on Windows 10, setting up Nginx, MariaDB, and PHP, configuring Magento, and testing the installation.…

This brief tutorial shows students and new users how to install the Magento eCommerce platform on Windows 10 WSL (Windows Subsystem for Linux) 2 with Nginx HTTP server on Ubuntu 20.04 | 18.04.

Magento 2 is one of the most popular eCommerce platforms today for successfully running online stores. It’s an open-source platform and works great in Linux systems, including Ubuntu.

Installing Magento 2 on Windows WSL (Windows Subsystem for Linux) allows Windows users to utilize the Magento eCommerce platform without switching to a Linux operating system. By enabling WSL in Windows, users can install a full Linux operating system inside Windows and run Magento on Ubuntu.

WSL 2 is an improvement over version 1, delivering features that make WSL a fantastic way to run a Linux environment in Windows. This option provides a performance boost and full system call compatibility. Magento 2 is an open-source platform that works great in Linux systems, including Ubuntu.

If you have a machine that meets the requirements above to run WSL 2, continue below.

To get started with running Magento on Windows with WSL, follow the steps below:

Enable WSL in Windows

To enable WSL in Windows, you will want to open the PowerShell terminal as administrator. Click on Start, then begin typing PowerShell.

Next, right-click the Windows PowerShell app and choose to run as administrator.

When the console opens, run the commands below:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

After installing, you should get a success message similar to the lines below:

Deployment Image Servicing and Management tool
Version: 10.0.19041.844

Image Version: 10.0.19042.844

Enabling feature(s)
[==========================100.0%==========================]
The operation completed successfully.

Enable Virtual Machine Platform

WSL 2 requires Windows 10 Virtual Machine Platform to be enabled. This is not Hyper-V. To enable the VM platform feature in Windows, run the commands below from the same PowerShell administrator’s console.

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

If you’re using Windows 10 version lower than 2004, then use the commands below:

Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -NoRestart

When you’re done running the commands above, restart your computer for all the configuration changes to apply. If you don’t restart, the below command might not be recognized.

After restarting your computer, log back in and launch PowerShell as administrator. Then, run the commands below to configure WSL 2 as the default version of WSL.

wsl --set-default-version 2

Install Ubuntu on Windows 10

Now that WSL 2 is installed and ready to be used, open the link below to download and install a copy of Ubuntu 20.04 from the Windows store.

Get Ubuntu 20.04 LTS – Microsoft Store

Ubuntu 20.04 LTS on Windows allows you to use Ubuntu Terminal and run Ubuntu command line utilities, including bash, ssh, git, apt, and many more.

Click the Get button and install. After installing Ubuntu, you’ll want the option to launch Ubuntu from the Windows WSL environment.

After launching, Ubuntu should install and prompt you to create your account.

Installing, this may take a few minutes.
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username: richard
New password:
Retype new password:
passwd: password updated successfully
Installation successful!
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

Welcome to Ubuntu 20.04.2 LTS (GNU/Linux 4.4.0-19041-Microsoft x86_64)

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/advantage

  System information as of Mon Apr 12 17:57:37 CDT 2021

  System load:    0.52      Processes:             7
  Usage of /home: unknown   Users logged in:       0
  Memory usage:   26%       IPv4 address for eth0: 10.0.2.15
  Swap usage:     0%

1 update can be installed immediately.
0 of these updates are security updates.
To see these additional updates run: apt list --upgradable

That should do it!

Some troubleshooting commands to run when you run into the issues above. These run below and try to relaunch the Ubuntu image.

wsl --set-default-version 1
bcdedit /set hypervisorlaunchtype auto start

Now that the Windows 10 WSL environment is ready install Nginx, MariaDB, and PHP and configure Magento.

Install Nginx HTTP Server

Magento requires a web server to function, and Nginx is one of the most popular open-source web servers available today.

To install Nginx on Ubuntu, run the commands below:

sudo apt update
sudo apt install nginx

After installing Nginx, the commands below can be used to stop and start Nginx services.

sudo service nginx stop
sudo service nginx start

To test whether Nginx is installed and functioning, open your web browser and browse to the server’s IP address or hostname.

http://localhost

If you see the above page in your browser, Nginx works as expected.

Install MariaDB Server

You’ll also need a database server to run Magento. A database server is where Magento content gets stored.

A truly open-source database server that you can use with Magento is the MariaDB database server. It is fast and secure and is the default server for almost all Linux servers.

To install MariaDB, run the commands below:

sudo apt install mariadb-server mariadb-client

After installing MariaDB, the commands below can stop and start the service and enable it to start when the server boots.

sudo service mysql stop
sudo service mysql start

Next, run the commands below to secure the database server with a root password if you were not prompted to do so during the installation.

sudo mysql_secure_installation

When prompted, answer the questions below by following the guide.

  • Enter current password for root (enter for none): Press the Enter
  • Set root password? [Y/n]: Y
  • New password: Enter password
  • Re-enter new password: Repeat password
  • Remove anonymous users? [Y/n]: Y
  • Disallow root login remotely? [Y/n]: Y
  • Remove test database and access to it? [Y/n]:  Y
  • Reload privilege tables now? [Y/n]:  Y

To verify and validate that MariaDB is installed and working, log in to the database console using the commands below:

sudo mysql -u root -p

Type the root password when prompted.

The server was successfully installed if you see a similar screen.

Install PHP and Related Modules

Magento is a PHP-based application, and PHP is required to run it. Run the commands below to install PHP and related modules to support Magento.

sudo apt install php-fpm php-common php-mysql php-gmp php-curl php-intl php-mbstring php-xmlrpc php-gd php-xml php-cli php-zip php-soap php-bcmath

After installing PHP, configure some basic settings that Magento may need to function correctly.

For this tutorial, PHP 7.4 was installed. Based on your environment, another version of PHP might be installed. So verify that.

sudo nano /etc/php/7.4/fpm/php.ini

Below are good settings to configure for most Magento websites.

file_uploads = On
allow_url_fopen = On
short_open_tag = On
memory_limit = 256M
cgi.fix_pathinfo = 0
upload_max_filesize = 100M
max_execution_time = 360
date.timezone = America/Chicago

That should get PHP 7.4 installed with some basic settings to allow Magento to function.

After setting up PHP, the command below can be used to stop and start PHP7.4 services.

sudo service php7.4-fpm stop
sudo service php7.4-fpm start

Create Magento Database

When all the servers are installed above, it’s time to begin setting up the Magento environment. First, run the steps below to create a blank database for Magento.

Login to the MariaDB database console using the commands below:

sudo mysql -u root -p

Then, create a database called magentodb

CREATE DATABASE magentodb;

Next, create a database user called magentodbuser and set a password

CREATE USER 'magentodbuser'@'localhost' IDENTIFIED BY 'new_password_here';

Then, grant the user full access to the database.

GRANT ALL ON magentodb.* TO 'magentodbuser'@'localhost' WITH GRANT OPTION;

Finally, save your changes and exit.

FLUSH PRIVILEGES;
EXIT;

Download Magento

At this point, Magento is ready to be downloaded and installed. Use the commands below to download the latest version of Magento.

To get Magento’s latest release, you may want to use the GitHub repository… Install Composer, Curl, and other dependencies to get started…

sudo apt install curl git
curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

When prompted, enter your authentication keys. Your public key is your username; your private key is your password….  ( https://marketplace.magento.com/customer/accessKeys/ )

You’ll have to register for an account to create the key above.

After installing curl and Composer above, change into the Nginx root directory and download Magento packages from GitHub… Always replace the branch number with the latest branch.

To view Magento releases, see this page.

cd /var/www/
sudo composer create-project --repository=https://repo.magento.com/ magento/project-community-edition magento

Copy and paste the authentication key… (Your public key is your username; your private key is your password)

Output:
Authentication required (repo.magento.com):
Username: 234f2343435d190983j0ew8u3220
Password: 
Do you want to store credentials for repo.magento.com in /opt/magento/.config/composer/auth.json ? [Yn] Y

After downloading Magento packages, run the commands below to install Magento with the following options:

cd /var/www/magento
sudo bin/magento setup:install --base-url=http://example.com/ --db-host=localhost --db-name=magentodb --db-user=magentodbuser --db-password=db_user_password_here --admin-firstname=Super --admin-lastname=Admin --admin-email=admin@example.com --admin-user=admin --admin-password=admin123 --language=en_US --currency=USD --timezone=America/Chicago --use-rewrites=1
  • The Magento software is installed in the root directory on localhost…. Admin is admin;  therefore, Your storefront URL is http://exmaple.com
  • The database server is on the same localhost as the webserver….
  • The database name is magentodb, and the magentodbuser and password are db_user_password_here
  • Uses server rewrites
  • The Magento administrator has the following properties:
    • First and last names are: Admin User
    • Username is: admin
  •  and the password is admin123
  • E-mail address is: admin@example.com
  • Default language is: (U.S. English)
  • Default currency is: U.S. dollars
  • Default time zone is: U.S. Central (America/Chicago)

Elasticsearch is now enabled with Magento packages. If you’re not using it and run into trouble after running the commands above, use this line to disable the Elasticsearch module.

sudo php bin/magento module:disable {Magento_Elasticsearch,Magento_InventoryElasticsearch,Magento_Elasticsearch6,Magento_Elasticsearch7}

If you want to run Magento with Elasticsearch instead, read this post.

After that, run the commands below to set the correct permissions for Magento 2 to function.

Then, run the command below to allow the www-data user to own the Magento directory.

sudo chown -R www-data:www-data /var/www/magento/
sudo chmod -R 755 /var/www/magento/

Configure the Nginx Server block

Below is where you configure the Nginx VirtualHost file for your Magento site. This file defines how client requests are handled and processed.

Run the commands below to create a new VirtualHost file called Magento in the /etc/nginx/sites-available/ directory.

sudo nano /etc/nginx/sites-available/magento

Below is a perfect configuration setting for most Magento sites on the Nginx server. This configuration should work great.

Copy the content below and save it into the file created above.

upstream fastcgi_backend {
  server unix:/run/php/php7.4-fpm.sock;
}

server {
    listen 80;
    listen [::]:80;

    server_name  example.com www.example.com;
    index  index.php;

    set $MAGE_ROOT /var/www/magento;
    set $MAGE_MODE production;

    access_log /var/log/nginx/example.com-access.log;
    error_log /var/log/nginx/example.com-error.log;

    include /var/www/magento/nginx.conf.sample;
}

Save the file and exit.

After saving the file above, run the commands below to enable the new site, then restart the Nginx server.

sudo ln -s /etc/nginx/sites-available/magento /etc/nginx/sites-enabled/
sudo service nginx restart

At this stage, Magento is ready and can be launched by going to the server’s IP or hostname.

https://example.com

That should bring up the Magento home page.

Log in with the account above, and you’re done.

That’s it!

Conclusion:

This post showed you how to install Magento on Windows 10 with Ubuntu. If you find any error above, please use the comment form below to report.

Like this:



3 responses to “How to Install Magento 2 on Windows WSL”

  1. jaimin Avatar
    jaimin

    Nice blog post Can you please add how to install PHPMyAdmin with Nginx on windows wsl I tried but getting issues and not working with this setup.

  2. Sol Avatar
    Sol

    missing elasticsearch here. which is a biggie, since it’s a mandatory for m2.3+

  3. Antonio Avatar
    Antonio

    Went through it but at the end when I go to example.com it just shows me

    Example Domain
    This domain is for use in illustrative examples in documents. You may use this domain in literature without prior coordination or asking for permission.

    More information…

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.