Restore the Porta On Prem WSL virtual disk

This guide will walk you through restoring the WSL virtual disk for Porta On Prem from a previously created backup.

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. Ensure your backup exists

1. Check your backup location for an existing and up to date .tar.
   • By default, if you followed the backup instructions, this is likely D:\wsl\backups\docker-desktop-data.tar.
2. If you do not have an up-to-date backup, return to this step after you have performed the backup instructions to create one.
3. If you have an up-to-date backup, proceed to the next section.

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

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.