Home

Awesome

Hypernode Docker WSL development environment

This repository contains a fully-featured Windows WSL development environment based on hypernode-docker adjusted to support OS integration features that come with WSL2 + WSLg on Windows 11. This repository also integrates JetBrains IDE's using WSLg and projector to overcome filesystem performance issues.

Features

Prerequisites

You should have setup WSL/WSLg fully before you can use this repository. I recommend to follow the Microsoft guides above to install WSL/WSLg and a distro, for example ubuntu. Your setup is ready when you are able to for example start gedit from the WSL environment.

Warning

The technologies used in this repository are fairly new and could be unstable. Also be aware of the security implications of using third-party WSL environments like this.

Installation

The WSL environment is build from a slightly modified hypernode-docker container using the Dockerfile in this repository.

1. Create the image

First we have to create the image by pulling it or building it ourselves.

Option: 1.a: pull the latest image

docker pull frosit/hypernode-docker-wsl:latest

Option: 1.b: build the image yourself

# or make build-container
docker build -t frosit/hypernode-docker-wsl:latest .

2. Create the container

docker create --name hnwsl frosit/hypernode-docker-wsl:latest

3. Export the container

docker export hnwsl -o hnwsl.tar

3. Import the container as WSL

I prefer to store my WSL environments under C:\WSL\<distro>. So for example create a directory C:\WSL\hypernode and then import the tar you exported earlier. For example:

wsl.exe --import hypernode C:\WSL\hypernode C:\WSL\hnwsl.tar

Restarting Windows terminal will automatically add the hypernode WSL to Windows terminal. You can use wsl.exe -d hypernode to enter the WSL environment.

Optional: Docker integration

It is possible to use docker while in the WSL environment to add for example a different MySQL version. To do this go to the "docker desktop app" under settings > Resources > WSL Integration and check the WSL environment. This will add a docker.sock within the WSL environment which is the same docker instance as your docker desktop.

Usage

After import, there are a few things you can do.

This image added sudo permissions to the app user and set the password to app. For root the password is root. You might want to change this: sudo passwd app

Bringing up services

By default, the ports of the hypernode are mapped to ports on localhost and you have to start the services yourself.

sudo service nginx start
sudo service php7.2-fpm start
sudo service mysql.distrib start
sudo service redis-server start

Then you can find your instance on http://localhost.

Switch PHP Version (@todo add)

@todo add switch php scripts

Starting an IDE using jetbrains-toolbox

Executing jetbrains-toolbox will bring up the toolbox dialogue from which you can install/start and IDE like PhpStorm. The first time could take a bit longer.

Starting an IDE as cloud/web app using Projector

The projector command has options to manage projector IDE's. To install use projector install. Afterwards you can use projector run <ide> to start the IDE.

note: projector is also new and slightly unstable. It should come on port 9999 of localhost

Install xDebug

To install run: sudo apt install php-xdebug. xdebug should be available right away.

@todo PhpStorm configurations

Issues

WSL2/WSLg has a few known issues. Information about these issues can be found here

Preview

Here's my current and main development environment using the hypernode-docker as WSL environment. Including a themed Windows Terminal.

terminal + jetbrains toolbox

Running PhpStorm from the hypernode environment using WSLg

phpstorm WSLg

PhpStorm in Edge using projector server

phpstorm projector server

asciicast

asciicast