Migrating Porta On Prem WSL data to a new location

This guide will walk you through migrating the WSL virtual disk for Porta On Prem to a new location on your system.

Note

Default location for docker-desktop-data is usually %LOCALAPPDATA%\Docker\wsl\data

Tip

These steps concern the internal docker distribution (“distro”) in which data for containers, volumes, etc. is stored. It does not affect the Ubuntu distro, which is on a separate virtual drive.

1. Backup the virtual disk

First, we want to create a database backup to ensure we have a restore point in case anything goes wrong.

1. Use the system tray to shut down Docker Desktop.
2. After Docker has finished shutting down, open Powershell.
3. Run wsl --shutdown to stop all distributions.
4. Run wsl -l -v and ensure the docker distros are stopped. A successful output will look like this:

   NAME                   STATE           VERSION
   * Ubuntu-22.04         Stopped         2
   docker-desktop-data    Stopped         2
   docker-desktop         Stopped         2

5. Export the docker-desktop-data distribution to a .tar file.

   1. Open powershell as an administrator.

   2. Confirm that docker-desktop-data exists and is stopped by running:

      wsl -l -v

      A successful output will look like this:

      NAME                   STATE           VERSION
      * Ubuntu-22.04         Stopped         2
      docker-desktop-data    Stopped         2
      docker-desktop         Stopped         2

   3. In Powershell, run the following command to export the docker-desktop-data distribution to a .tar file.

      • In the command, replace D:\path\to\backup with your desired backup directory.
        • This directory must already exist prior to exporting. Create a new directory if necessary.
      • Make sure the export destination has enough free disk space.
      • The export may take a while if the virtual disk is large (anywhere from 5 to 15 minutes).

      • wsl --export docker-desktop-data D:\path\to\backup\docker-desktop-data.tar

   4. You’ll know the export has finished when the PS C:\Users\username> prompt appears again on the next line.

6. Verify the backup file was created successfully.
   1. Navigate to the backup directory you specified in step 2.
   2. Confirm that the docker-desktop-data.tar file exists.
   3. Check the file size to ensure it’s greater than 0 bytes.

Tip

Note the name of the backup file that was created, because we’ll need it in the next steps.

2. Confirm that your target drive is formatted as NTFS

Caution

The virtual disk used by WSL requires the host drive to be formatted as NTFS.

If your target drive is formatted as exFAT, FAT32, ReFS, or a network share, the restoration will fail.

1. In Explorer, navigate to This PC.
2. Right-click the drive you want to restore to and select properties from the context menu.
3. In the window that opens, check the File system property.

3. Locate your existing virtual disk

1. In Explorer, navigate to %LOCALAPPDATA%\Docker\wsl\data to find your existing virtual disk file, named ext4.vhdx.
2. You can also check Docker Desktop’s Settings > Resources > Advanced and check its Disk image location.
3. Note this path so that we can copy it for use later.

4. Shut down Docker Desktop

1. Use the system tray to quit Docker Desktop.
2. Open Powershell.
3. Run wsl --shutdown to stop all distributions.
4. Run wsl -l -v and ensure the docker distros are stopped. A successful output will look like this:

   NAME                   STATE           VERSION
   * Ubuntu-22.04         Stopped         2
   docker-desktop-data    Stopped         2
   docker-desktop         Stopped         2

5. Unregister (delete) the existing docker-desktop-data distribution

Warning

If you execute the following steps without a backup to restore from, all Porta data and files will be permanently lost on this machine.

1. Open Powershell as an administrator.

2. Confirm that docker-desktop-data exists and is stopped by running:

   wsl -l -v

   A successful output will look like this:

   NAME                   STATE           VERSION
   * Ubuntu-22.04         Stopped         2
   docker-desktop-data    Stopped         2
   docker-desktop         Stopped         2

3. In Powershell, run the following command to unregister (delete) the docker-desktop-data distribution:

   wsl --unregister docker-desktop-data

4. You will not receive any confirmation message, but you can verify it was removed by running wsl -l -v again.

   • The output should no longer list docker-desktop-data:

   NAME                   STATE           VERSION
   * Ubuntu-22.04         Stopped         2
   docker-desktop         Stopped         2

5. You can also check the disk location in Windows explorer (likely %LOCALAPPDATA%\Docker\wsl\data) to ensure that the ext4.vhdx file was removed.

6. Restore the virtual disk to the new location

Now that we have a backup, we can proceed to restore the virtual disk to the new location.

1. Ensure that the folder that you will be restoring your data to already exists, e.g., %LOCALAPPDATA%\Docker\wsl\data, or D:\wsl\docker-desktop-data.

2. Import the data to restore the docker-desktop-data distribution from your backup .tar file.

   1. Open Powershell.
   2. Run the following command to import the backup.
      • Replace D:\path\to\backup with the path to your backup file.
      • Replace D:\path\to\restore\folder with the path to your restore destination directory.

      wsl --import docker-desktop-data "D:\path\to\restore\folder" "D:\path\to\backup\docker-desktop-data.tar" --version 2

   3. You’ll know the import has finished when the PS C:\Users\username> prompt appears again on the next line.

   Note

   Import may take up to 15 minutes, depending on the size of the virtual disk.

3. After the import has finished, confirm that the distro is recognized in WSL by opening Powershell and running:

   wsl -l -v

   A successful output will look like this:

   NAME                   STATE           VERSION
   * Ubuntu-22.04         Stopped         2
   docker-desktop-data    Stopped         2
   docker-desktop         Stopped         2

4. Start Docker Desktop again. It should find and use the newly imported docker-desktop-data distribution.

5. After starting Docker, in Powershell, run a quick docker images or docker volume ls command to confirm your images/volumes are still present.

6. Everything should be back to normal now.