Merge pull request #153 from KernelGhost/main

Improved 'Docker' and 'Podman' Installation Documentation + New README Image
2025-06-23 22:53:02 +02:00 · 2024-07-23 17:18:29 +10:00 · 2024-07-23 17:18:29 +10:00 · 7329ef9a99
commit 7329ef9a99
parent 3bdf548699 7416c0a750
6 changed files with 140 additions and 24 deletions
--- a/README.md
+++ b/README.md
@ -4,7 +4,7 @@

 Run Windows applications (including [Microsoft 365](https://www.microsoft365.com/) and [Adobe Creative Cloud](https://www.adobe.com/creativecloud.html)) on GNU/Linux with `KDE`, `GNOME` or `XFCE`, integrated seamlessly as if they were native to the OS.

-<img src="demo/demo.gif" width=1000 alt="WinApps Demonstration Animation.">
+<p align="center"><img src="./demo/demo.png" width=1000 alt="WinApps Demonstration."></p>

 ## Underlying Mechanism
 WinApps works by:
@ -16,6 +16,7 @@ WinApps works by:
 ## Additional Features
 - The GNU/Linux `/home` directory is accessible within Windows via the `\\tsclient\home` mount.
 - Integration with `Nautilus`, allowing you to right-click files to open them with specific Windows applications based on the file MIME type.
+- The [official taskbar widget](https://github.com/winapps-org/WinApps-Launcher) enables seamless administration of the Windows subsystem and offers an easy way to launch Windows applications.

 ## Supported Applications
 **WinApps supports <u>*ALL*</u> Windows applications.**
@ -328,7 +329,7 @@ Run the WinApps installer.

 A list of supported additional arguments can be accessed by running `./installer.sh --help`.

-<img src="demo/installer.gif" width=1000 alt="WinApps Installer Animation.">
+<img src="./demo/installer.gif" width=1000 alt="WinApps Installer Animation.">

 ## Adding Additional Pre-defined Applications
 Adding your own applications with custom icons and MIME types to the installer is easy. Simply copy one of the application configurations in the `apps` folder located within the WinApps repository, and:
--- a/bin/winapps
+++ b/bin/winapps
@ -312,6 +312,7 @@ function waRunCommand() {
            +home-drive \
            /audio-mode:1 \
            /wm-class:"Microsoft Windows" \
+            /t:"Windows RDP Session [$RDP_IP]" \
            /v:"$RDP_IP" &>/dev/null &
    elif [ "$1" = "manual" ]; then
        # Open specified application.
--- a/demo/demo.gif
+++ b/demo/demo.gif
--- a/demo/demo.png
+++ b/demo/demo.png
--- a/docs/docker.md
+++ b/docs/docker.md
@ -12,10 +12,7 @@ Although WinApps supports using `QEMU+KVM+libvirt` as a backend for running Wind
 You can find a guide for installing `Docker Engine` [here](https://docs.docker.com/engine/install/).

 ### Setup `Docker` Container
-WinApps utilises `docker compose` to configure Windows VMs.
-
-> [!IMPORTANT]
-> The [`compose.yaml`](https://github.com/winapps-org/winapps/blob/main/compose.yaml) file located within the root directory of the WinApps repository must be manually copied to `~/.config/winapps/compose.yaml`.
+WinApps utilises `docker compose` to configure Windows VMs. A template [`compose.yaml`](https://github.com/winapps-org/winapps/blob/main/compose.yaml) is provided.

 Prior to installing Windows, you can modify the RAM and number of CPU cores available to the Windows VM by changing `RAM_SIZE` and `CPU_CORES` within `compose.yaml`.

@ -29,11 +26,29 @@ Please refer to the [original GitHub repository](https://github.com/dockur/windo
 ### Installing Windows
 You can initiate the Windows installation using `docker compose`.
 ```bash
-docker compose --file ~/.config/winapps/compose.yaml up
+cd winapps
+docker compose --file ./compose.yaml up
 ```

 You can then access the Windows virtual machine via a VNC connection to complete the Windows setup by navigating to http://127.0.0.1:8006 in your web browser.

+After installing Windows, comment out the following lines in the `compose.yaml` file by prepending a '#':
+- `- ./oem:/oem`
+- `- /path/to/windows/install/media.iso:/custom.iso` (if relevant)
+
+Then, copy this modified `compose.yaml` file to `~/.config/winapps/compose.yaml`.
+
+```bash
+cp ./compose.yaml ~/.config/winapps/compose.yaml
+```
+
+Finally, ensure the new configuration is applied by running the following:
+
+```bash
+docker compose --file ./compose.yaml down
+docker compose --file ~/.config/winapps/compose.yaml up
+```
+
 ### Installing WinApps
 `Docker` simplifies the WinApps installation process by eliminating the need for any additional configuration of the Windows virtual machine. Once the Windows virtual machine is up and running, you can directly launch the WinApps installer, which should automatically detect and interface with Windows.

@ -45,12 +60,18 @@ You can then access the Windows virtual machine via a VNC connection to complete
 ```

 ### Changing `compose.yaml`
-Changes require the Windows virtual machine to be removed and re-created using the updated `compose.yaml`. This should __NOT__ affect your data.
+Changes to `compose.yaml` require the Windows virtual machine to be removed and re-created. This should __NOT__ affect your data.

 ```bash
-docker compose --file ~/.config/winapps/compose.yaml down # Stop and remove the existing Windows virtual machine.
-rm ~/.config/freerdp/server/127.0.0.1_3389.pem # Remove the existing FreeRDP certificate (a new certificate will be created automatically when connecting to the new virtual machine for the first time).
-docker compose --file ~/.config/winapps/compose.yaml up # Re-create the virtual machine with the updated configuration.
+# Stop and remove the existing Windows virtual machine.
+docker compose --file ~/.config/winapps/compose.yaml down
+
+# Remove the existing FreeRDP certificate (if required).
+# Note: A new certificate will be created when connecting via RDP for the first time.
+rm ~/.config/freerdp/server/127.0.0.1_3389.pem
+
+# Re-create the virtual machine with the updated configuration.
+docker compose --file ~/.config/winapps/compose.yaml up
 ```

 ### Subsequent Use
@ -71,22 +92,52 @@ docker compose --file ~/.config/winapps/compose.yaml kill # Force shut down the
 ### Setup `Podman` Container
 Please follow the [`docker` instructions](#setup-docker-container).

-> [!NOTE]
+> [!IMPORTANT]
 > Ensure `WAFLAVOR` is set to `"podman"` in `~/.config/winapps/winapps.conf`.

 ### Installing Windows
 You can initiate the Windows installation using `podman-compose`.
 ```bash
-podman-compose --file ~/.config/winapps/compose.yaml up
+cd winapps
+podman-compose --file ./compose.yaml up
 ```

 You can then access the Windows virtual machine via a VNC connection to complete the Windows setup by navigating to http://127.0.0.1:8006 in your web browser.

+After installing Windows, comment out the following lines in the `compose.yaml` file by prepending a '#':
+- `- ./oem:/oem`
+- `- /path/to/windows/install/media.iso:/custom.iso` (if relevant)
+
+Then, copy this modified `compose.yaml` file to `~/.config/winapps/compose.yaml`.
+
+```bash
+cp ./compose.yaml ~/.config/winapps/compose.yaml
+```
+
+Finally, ensure the new configuration is applied by running the following:
+
+```bash
+podman-compose --file ./compose.yaml down
+podman-compose --file ~/.config/winapps/compose.yaml up
+```
+
 ### Installing WinApps
 Please follow the [`docker` instructions](#installing-winapps).

 ### Changing `compose.yaml`
-Please follow the [`docker` instructions](#changing-composeyaml).
+Changes to `compose.yaml` require the Windows virtual machine to be removed and re-created. This should __NOT__ affect your data.
+
+```bash
+# Stop and remove the existing Windows virtual machine.
+podman-compose --file ~/.config/winapps/compose.yaml down
+
+# Remove the existing FreeRDP certificate (if required).
+# Note: A new certificate will be created when connecting via RDP for the first time.
+rm ~/.config/freerdp/server/127.0.0.1_3389.pem
+
+# Re-create the virtual machine with the updated configuration.
+podman-compose --file ~/.config/winapps/compose.yaml up
+```

 ### Subsequent Use
 ```bash
--- a/installer.sh
+++ b/installer.sh
@ -460,14 +460,11 @@ function waLoadConfig() {
    echo -e "${DONE_TEXT}Done!${CLEAR_TEXT}"
 }

-# Name: 'waCheckDependencies'
+# Name: 'waCheckScriptDependencies'
 # Role: Terminate script if dependencies are missing.
-function waCheckDependencies() {
-    # Declare variables.
-    local FREERDP_MAJOR_VERSION="" # Stores the major version of the installed copy of FreeRDP.
-
+function waCheckScriptDependencies() {
    # Print feedback.
-    echo -n "Checking whether all dependencies are installed... "
+    echo -n "Checking whether installation script dependencies are installed... "

    # 'Dialog'.
    if ! command -v dialog &>/dev/null; then
@ -495,6 +492,43 @@ function waCheckDependencies() {
        # Terminate the script.
        return "$EC_MISSING_DEPS"
    fi
+}
+
+# Name: 'waCheckInstallDependencies'
+# Role: Terminate script if dependencies required to install WinApps are missing.
+function waCheckInstallDependencies() {
+    # Declare variables.
+    local FREERDP_MAJOR_VERSION="" # Stores the major version of the installed copy of FreeRDP.
+
+    # Print feedback.
+    echo -n "Checking whether dependencies are installed... "
+
+    # 'Netcat'
+    if ! command -v nc &>/dev/null; then
+        # Complete the previous line.
+        echo -e "${FAIL_TEXT}Failed!${CLEAR_TEXT}\n"
+
+        # Display the error type.
+        echo -e "${ERROR_TEXT}ERROR:${CLEAR_TEXT} ${BOLD_TEXT}MISSING DEPENDENCIES.${CLEAR_TEXT}"
+
+        # Display the error details.
+        echo -e "${INFO_TEXT}Please install 'netcat' to proceed.${CLEAR_TEXT}"
+
+        # Display the suggested action(s).
+        echo "--------------------------------------------------------------------------------"
+        echo "Debian/Ubuntu-based systems:"
+        echo -e "  ${COMMAND_TEXT}sudo apt install netcat${CLEAR_TEXT}"
+        echo "Red Hat/Fedora-based systems:"
+        echo -e "  ${COMMAND_TEXT}sudo dnf install nmap-ncat${CLEAR_TEXT}"
+        echo "Arch Linux systems:"
+        echo -e "  ${COMMAND_TEXT}sudo pacman -S gnu-netcat${CLEAR_TEXT}"
+        echo "Gentoo Linux systems:"
+        echo -e "  ${COMMAND_TEXT}sudo emerge --ask net-analyzer/netcat${CLEAR_TEXT}"
+        echo "--------------------------------------------------------------------------------"
+
+        # Terminate the script.
+        return "$EC_MISSING_DEPS"
+    fi

    # 'FreeRDP' (Version 3).
    # Attempt to set a FreeRDP command if the command variable is empty.
@ -559,7 +593,7 @@ function waCheckDependencies() {
        return "$EC_MISSING_DEPS"
    fi

-    # 'libvirt' / 'virt-manager'.
+    # 'libvirt'/'virt-manager' + 'Address Resolution Protocol'.
    if [ "$WAFLAVOR" = "libvirt" ]; then
        if ! command -v virsh &>/dev/null; then
            # Complete the previous line.
@ -586,6 +620,32 @@ function waCheckDependencies() {
            # Terminate the script.
            return "$EC_MISSING_DEPS"
        fi
+
+        if ! command -v arp &>/dev/null; then
+            # Complete the previous line.
+            echo -e "${FAIL_TEXT}Failed!${CLEAR_TEXT}\n"
+
+            # Display the error type.
+            echo -e "${ERROR_TEXT}ERROR:${CLEAR_TEXT} ${BOLD_TEXT}MISSING DEPENDENCIES.${CLEAR_TEXT}"
+
+            # Display the error details.
+            echo -e "${INFO_TEXT}Please install 'net-tools' to proceed.${CLEAR_TEXT}"
+
+            # Display the suggested action(s).
+            echo "--------------------------------------------------------------------------------"
+            echo "Debian/Ubuntu-based systems:"
+            echo -e "  ${COMMAND_TEXT}sudo apt install net-tools${CLEAR_TEXT}"
+            echo "Red Hat/Fedora-based systems:"
+            echo -e "  ${COMMAND_TEXT}sudo dnf install net-tools${CLEAR_TEXT}"
+            echo "Arch Linux systems:"
+            echo -e "  ${COMMAND_TEXT}sudo pacman -S net-tools${CLEAR_TEXT}"
+            echo "Gentoo Linux systems:"
+            echo -e "  ${COMMAND_TEXT}sudo emerge --ask sys-apps/net-tools${CLEAR_TEXT}"
+            echo "--------------------------------------------------------------------------------"
+
+            # Terminate the script.
+            return "$EC_MISSING_DEPS"
+        fi
    elif [ "$WAFLAVOR" = "docker" ]; then
        if ! command -v docker &>/dev/null; then
            # Complete the previous line.
@ -1390,7 +1450,7 @@ function waInstall() {
    waLoadConfig

    # Check for missing dependencies.
-    waCheckDependencies
+    waCheckInstallDependencies

    # Update $MULTI_FLAG.
    if [[ $MULTIMON == "true" ]]; then
@ -1422,7 +1482,7 @@ function waInstall() {
        waCheckContainerRunning
    elif [ "$WAFLAVOR" = "libvirt" ]; then
        # Verify the current user's group membership.
-        waCheckGroupMembership # Check membership
+        waCheckGroupMembership

        # Check if the Windows VM is powered on.
        waCheckVMRunning
@ -1545,7 +1605,7 @@ function waUninstall() {
    # Print caveats.
    echo -e "\n${INFO_TEXT}Please note your WinApps configuration folder was not removed.${CLEAR_TEXT}"
    echo -e "${INFO_TEXT}You can remove this manually by running:${CLEAR_TEXT}"
-    echo -e "${COMMAND_TEXT}rm $(dirname "$CONFIG_PATH")${CLEAR_TEXT}\n"
+    echo -e "${COMMAND_TEXT}rm -r $(dirname "$CONFIG_PATH")${CLEAR_TEXT}\n"

    # Print feedback.
    echo -e "${SUCCESS_TEXT}UNINSTALLATION COMPLETE.${CLEAR_TEXT}"
@ -1561,6 +1621,9 @@ echo -e "${BOLD_TEXT}\
 ################################################################################
 ${CLEAR_TEXT}"

+# Check dependencies for the script.
+waCheckScriptDependencies
+
 # Source the contents of 'inquirer.sh'.
 # shellcheck source=/dev/null # Exclude this file from being checked by ShellCheck.
 source "$INQUIRER_PATH"