Important

You are browsing documentation for version 5.1 of OroCommerce, supported until March 2026. Read the documentation for version 6.0 (the latest LTS version) to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Set up Environment for OroPlatform Based Application on Windows Subsystem for Linux (WSL) 2

This guide demonstrates how to set up Docker and Symfony Server development stack for Oro applications on Windows 10, version 1903 or higher. Please make sure you have the latest version of the Windows OS before you start.

Environment Setup

1. Install Ubuntu 20.04 LTS from the Microsoft Store to use with WSL 2. Alternatively, you can install it with a WSL command wsl --install -d Ubuntu, followed by wsl --set-version Ubuntu 2

2. Install Windows Terminal. It is not required to use a Windows Terminal/Powershell but we recommend using it as it comes with the built-in WSL integration. Please make sure that you run your windows terminal as an administrator. You may be prompted to reboot your PC after installation.

   

   If you encounter an error during installation, please follow the link provided in the terminal to troubleshoot the issue or refer to the official Microsoft WSL documentation:

   

   Once rebooted, create a new NIX username and password to log into Ubuntu.

   

   To switch to Ubuntu on your Windows Powershell, click on the dropdown next to the + tab and select Ubuntu from the list.

   

   To avoid switching to Ubuntu manually every time, you can set up your Windows Powershell to run Ubuntu by default on startup. For this, navigate to your Windows settings > Startup and change the Default Profile to Ubuntu, as illustrated in the screenshot below:

   

   As WSL integration does not always work well with the Windows file system, go to the Linux file system by typing in cd in the terminal:

   

3. Install Docker Desktop for Windows. During installation, make sure that the checkbox for Install required Windows components for WSL 2 is selected. Reboot your PC once the installation is finished.

   

4. Enable Docker Desktop WSL 2 backend for the Ubuntu 20.04 LTS distribution that you installed at step 1.

   • In the General Settings of the Docker application, make sure that Use the WSL 2 based engine option is selected.

   • In the Resources > WSL Integration settings, enable option Ubuntu. Apply all changes and restart Docker.

   

5. Log into Ubuntu 20.04 LTS using Windows Terminal. All the below commands will be executed in it.

6. Install PHP 8.2 with all required extensions to Ubuntu 20.04 LTS:

   Hint

   It is recommended to run all commands one by one to make sure they exit successfully and avoid missing potential warnings. If you have unreliable connection leading to command failure, please rerun it.

   sudo apt install software-properties-common
   sudo add-apt-repository -y ppa:ondrej/php
   sudo apt update
   sudo apt -y install php8.2 php8.2-fpm php8.2-cli php8.2-pdo php8.2-mysqlnd php8.2-xml php8.2-soap php8.2-gd php8.2-zip php8.2-intl php8.2-mbstring php8.2-opcache php8.2-curl php8.2-bcmath php8.2-ldap php8.2-pgsql php8.2-dev php8.2-mongodb
   

You will be prompted to type in your password as you are running the commands as a sudo user.

7. Configure PHP:

   echo -e "memory_limit = 2048M \nmax_input_time = 600 \nmax_execution_time = 600 \nrealpath_cache_size=4096K \nrealpath_cache_ttl=600 \nopcache.enable=1 \nopcache.enable_cli=0 \nopcache.memory_consumption=512 \nopcache.interned_strings_buffer=32 \nopcache.max_accelerated_files=32531 \nopcache.save_comments=1" | sudo tee -a  /etc/php/8.2/fpm/php.ini
   echo -e "memory_limit = 2048M" | sudo tee -a  /etc/php/8.2/cli/php.ini
   

8. Install Node.js 18:

   sudo apt -y install curl dirmngr apt-transport-https lsb-release ca-certificates
   curl -sL https://deb.nodesource.com/setup_16.x | sudo -E bash -
   sudo apt -y install nodejs
   

9. Install Composer:

   php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" && php composer-setup.php
   php -r "unlink('composer-setup.php');"
   sudo mv composer.phar /usr/bin/composer
   

10. Install Symfony Server:

    sudo apt -y install libnss3-tools
    wget https://get.symfony.com/cli/installer -O - | bash
    echo 'PATH="$HOME/.symfony/bin:$PATH"' >> ~/.bashrc
    source ~/.bashrc
    symfony server:ca:install
    

    You can also enable TLS, but as Symfony Server does not automate certificate installation for WSL on Windows, you have to copy the generated certificate manually from the /usr/local/share/ca-certificates/ folder to the host filesystem and install it manually to your web browser:

    

    An example of importing a certificate in Chrome:

    

11. Configure the network. WSL 2 changes the way networking is configured compared to WSL 1. You need to enable proxy of traffic to permit the traffic through the Windows firewall.

    Run in Ubuntu ip addr | grep eth0 to see the IP address of the WSL 2 virtual machine.

    

    Map WSL 2 port to the internal host netsh interface portproxy add v4tov4 listenport=8000 listenaddress=0.0.0.0 connectport=8000 connectaddress=172.22.33.170.

    Configure Windows Defender Firewall, as illustrated below:

    

12. Restart the terminal and the web browser to get them ready.

What’s Next

• Tips and Recommendations

• Installation of the Oro Application via the Command-Line Interface

• Consider using the Visual Studio Code or PhpStorm with the built-in WSL integration for development.