Windows Subsystem Build

This builds an Windows Subsystem Linux (WSL) tarball image for CDC as part of the developer experience. Builds are currently .

Specific Centers Implementation

Other Centers within CDC has already started their own implementation of distros for Windows Subsystem Linux (WSL) due to specialized needs of those centers.

For example,

• Centers for Forecast Analytics and Outbreaks (CFA) Virtual Analytics Platform (VAP) contains an Ubuntu based image with R, Python, and specialized disk mounts for a CFA developer's needs.
• NCEZID - Office of the Advanced Molecular Detection Platform (OAMDP) includes an Ubuntu based image with a series of steps to install an Ubuntu image with podman, python, and Github API (gh).
• CDC Data Hub (CDH) Lifecycle, Analysis, Visualization Accelerator (LAVA) Guide provides a guide for data scientists working within EDAV or another data pipelines.

Prerequisities

For requirements and prerequisities, go to docs/prerequisities.md.

How to use this?

Make sure WSL2 is setup properly by opening powershell and typing wsl.

Note: when running wsl for the first time, WSL will require administrative rights using your -su account in powershell. The username is your 4 letter user name + -su (ex. tpz7-su) and the password is in CyberArk.

1. Download the latest release.

2. Import a tar file and wait a bit. wsl --import <distroName> <virtual hard disk> <tar file>

3. Set it as the default distro: wsl --set-default <distroName>

4. Once imported, run the distro. This first time, you will be logged in as root while the run-once script runs: wsl or wsl -d <distroName>

5. Logout and either wait 1 minute, or else run the following command to ensure the distro restarts: wsl --terminate <distroName>

6. Login again and you should be logged in as your default non-root user with sudo access and DNS should be working going forward.

Example:

For the Ubuntu 24.04 distro, with a virtual hard disk path of C:\Users\tpz7\ubuntu-24.04-vhd and the tar file in C:\Users\tpz7\Downloads\ubuntu-24.04-cdc.tar

1. wsl --import ubuntu-24.04-cdc C:\Users\tpz7\ubuntu-24.04-vhd C:\Users\tpz7\Downloads\ubuntu-24.04-cdc.tar

2. Run the distro once to trigger the run-once actions: wsl -d ubuntu-24.04-cdc

3. Logout and terminate the distro: wsl --terminate ubuntu-24.04-cdc

4. Login again: wsl -d ubuntu-24.04-cdc

Installing Extra Tools

Inside the image, the /opt/scripts folder has a script to install an additional list of tools.

To install this list of tools, run bash /opt/scripts/add-extra-tools.sh. We couldn't fit it all into the image due to a 2GB restriction.

First-time login automation

Inside the image, the /opt/scripts folder has a run-once script to perform one-time automated actions. This script is run automatically on startup by the run-once.service systemd unit.

Setting the default login user

When you login for the first time, the run-once script creates a non-root user account based on your windows username and sets it as the default login user in /etc/wsl.conf.

If you login again and still see the root user prompt, then logout and wait for 1 minute before logging back in and you should see your regular user prompt. From then on, all subsequent logins will default to your non-root user account, which has sudo privileges. To sudo to the root user, type sudo su root, or sudo su - root to include the root environment. Packages requiring non-root user accounts with sudo access, such as homebrew can then be installed.

If you wish to change the default login back to root, change the default user entry in /etc/wsl.conf to root and logout and terminate the distro before logging in again: wsl --terminate <distroName>.

Configuring DNS

Also on first login, the run-once script will configure DNS resolution by getting the resolver IP or IPs from your Windows DNS configuration and adding them as nameserver entries to /etc/resolv.conf. This fixes a known issue with WSL's default DNS configuration. If you further customize the file, the script will not overwrite your changes as long as the file is not empty. Conversely, if you need to reset the DNS configuration, leave the file empty and logout and either terminate the distro directly, i.e. from a command shell: wsl --terminate <distro_name>, or wait one minute after logging out before logging back in, which should trigger the DNS configuration again.

Change Tool versions

We utilize mise to install common programming tools and it comes with a tool versions file.

To update or change the version of these tools, change the version of the tool in the file; ex. python 3.12.9, save the file, and run mise upgrade.

Once it is completed, you can run python -v with python 3.12.9.

Use mise list to figure out the available versions of python you can install.

WSL Tricks

To find out what distros are running, run wsl --list --running.

To shutdown WSL distros, run wsl --shutdown and wait 8 seconds.

When using wsl --image to run the image, it always logs you in as the root user.

For whatever reason, occasionally if you run wsl --shutdown, you may end up crashing the Windows vmcompute service, so running wsl to log back into your default machine will incur an error:
Logon failure: the user has not been granted the requested logon type at this computer, with an error code of wsl/service/CreateInstance/CreateVm.

If that occurs, fix it like this (does not require restarting):

1. (Optional) Run gpupdate /force to ensure you're up to day with Group Policy settings with the rest of the Enterprise. This could take up to 10 minutes. This probably won't fix your problem either, but good to keep updated on your own terms. Continue on!
2. Find your -su user password and open an administrative powershell.
3. Restart the vmcompute service by running Restart-Service vmcompute in your admin powershell.
4. Try using wsl again.

It is possible to navigate the filesystem of the distro by going to \wsl$\ and finding the distribution folder using Windows. Otherwise, one quick way to access it is to wsl -d <distro> and go to the root cd ~ and then run explorer.exe ., a Window will pop up going to the filesystem.

For more troubleshooting, visit Microsoft WSL Troubleshooting.

Local Testing

• Build the Container: bash build.sh

• Run a simple curl: podman run -t ubuntu-24.04-cdc bash -c "curl -vv google.com"

• Check whether going to google.com works: podman run -t ubuntu-24.04-cdc bash -c "bash /opt/scripts/check-google.sh"

• Download additional software: podman run -t ubuntu-24.04-cdc bash -c "bash /opt/scripts/add-extra-tools.sh"

Releases

We utilize Conventional Commits messages and automated tagging via Semantic Versioning.

The most important prefixes you should have in mind when writing git commit messages are:

fix: which represents bug fixes, and correlates to a SemVer patch.
feat: which represents a new feature, and correlates to a SemVer minor.
feat!:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.

Review through commit-analyzer for a set of meaningful terms to use.

Ongoing Issues

• mise should be accessible by all Linux users in the WSL distro
• Github Releases per file has a upper limit of 2GB.
  • Sort of fixed - slim down the image.

External Guides on making WSL work

• mvaisakh/wsl-distro-tars - teaches us how to build a tar file for a Linux distro
• Linux user creation for WSL - on how to create a default user for a manually installed WSL distro
• Finding Windows username from WSL - on access to cmd.exe via WSL (apparently cmd is accessible via WSL by default)