You are browsing upcoming documentation for version 5.1 of OroCommerce, OroCRM, and OroPlatform, scheduled for release in March 2023. Read version 5.0 (the latest LTS version) of the Oro documentation 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.
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
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
cdin the terminal:
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.
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.
Log into Ubuntu 20.04 LTS using Windows Terminal. All the below commands will be executed in it.
Install PHP 8.2 with all required extensions to Ubuntu 20.04 LTS:
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.
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
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
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
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:
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 eth0to 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:
Restart the terminal and the web browser to get them ready.
- 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.