Build a WSL Container Image¶

KIWI NG is capable of building WSL images using the appx utility. Make sure you have installed a package that provides this command on your build host.

Once the build host has the appx installed, the following image type setup is required in the XML description config.xml:

<type image="appx" metadata_path="/meta/data"/>

The /meta/data path specifies a path that provides additional information required for the WSL-DistroLauncher. This component consists out of a Windows(exe) executable file and an AppxManifest.xml file which references other files like icons and resource configurations for the startup of the container under Windows.

Note

/meta/data

Except for the root filesystem tarball KIWI NG is not responsible for providing the meta data required for the WSL-DistroLauncher. It is expected that the given metadata path contains all the needed information. Typically this information is delivered in a package provided by the Distribution and installed on the build host

Setup of the WSL-DistroLauncher¶

The contents of the AppxManifest.xml will be changed by KIWI NG if a containerconfig section is provided in the XML description. In the context of a WSL image the following container configuration parameters are taken into account:

<containerconfig name="my-wsl-container">
    <history
        created_by="Organisation"
        author="Name"
        application_id="AppIdentification"
        package_version="https://docs.microsoft.com/en-us/windows/uwp/publish/package-version-numbering"
        launcher="WSL-DistroLauncher-exe-file"
    >Container Description Text</history>
</containerconfig>

All information provided here including the entire section is optional. If not provided the existing AppxManifest.xml stays untouched.

created_by: Provides the name of a publisher organisation. An appx container needs to be signed off with a digital signature. If the image is build in the Open Build Service (OBS) this happens automatically. Outside of OBS one needs to make sure the given publisher organisation name matches the certificate used for signing.
author: Provides the name of the author and maintainer of this container
application_id: Provides an ID name for the container. The name must start with a letter and only allows alphanumeric characters. KIWI NG will not validate the given name string because there is no common criteria between the container architectures. KIWI NG just accepts any text.
package_version: Provides the version identification for the container. KIWI NG validates this against the Microsoft Package Version Numbering rules.
launcher: Provides the binary file name of the launcher .exe file.

Warning

There is no validation by KIWI NG if the contents of AppxManifest.xml are valid or complete to run the container. Users will find out at call time, not before

The following example shows how to build a WSL image based on openSUSE TW:

Make sure you have checked out the example image descriptions, see Example Appliance Descriptions.
Include the Virtualization/WSL repository to your list:
```
$ zypper addrepo http://download.opensuse.org/repositories/Virtualization:/WSL/<DIST> WSL
```
where the placeholder <DIST> is the preferred distribution.
Install fb-util-for-appx utility and a package that provides the WSL-DistroLauncher metadata. See the above note about /meta/data
```
$ zypper in fb-util-for-appx DISTRO_APPX_METADATA_PACKAGE
```
Note

If you are building in the Open Build Service make sure to add the packages from the zypper call above to your project config via osc meta -e prjconf and a line of the form support: PACKAGE_NAME for each package that needs to be installed on the Open Build Service worker that runs the KIWI NG build process.

Setup the image type:

Edit the XML description file: kiwi/build-tests/x86/tumbleweed/test-image-wsl/appliance.kiwi and add the following type and containerconfig:

<type image="appx" metadata_path="/meta/data">
    <containerconfig name="Tumbleweed">
        <history
            created_by="SUSE"
            author="KIWI-Team"
            application_id="tumbleweed"
            package_version="2003.12.0.0"
            launcher="openSUSE-Tumbleweed.exe"
        >Tumbleweed Appliance text based</history>
    </containerconfig>
</type>

Warning

If the configured metadata path does not exist the build will fail. Furthermore there is no validation by KIWI NG that the contents of the metadata path are valid or complete with respect to the requirements of the WSL-DistroLauncher

Build the image with KIWI NG:

$ sudo kiwi-ng system build \
    --description kiwi/build-tests/x86/tumbleweed/test-image-wsl \
    --set-repo http://download.opensuse.org/tumbleweed/repo/oss \
    --target-dir /tmp/myimage

Testing the WSL image¶

For testing the image a Windows 10 system is required. As a first step the optional feature named Microsoft-Windows-Subsystem-Linux must be enabled. For further details on how to setup the Windows machine see the following documentation: Windows Subsystem for Linux