diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 251dab7..f570dd9 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -6,13 +6,13 @@ repos: rev: v1.5.5 hooks: - id: chmod - args: ["775"] + args: [ "775" ] files: (\.sh|winapps)$ - id: forbid-crlf - id: remove-crlf - id: forbid-tabs - id: remove-tabs - args: [--whitespaces-count, "2"] + args: [ --whitespaces-count, "2" ] - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.6.0 @@ -36,16 +36,14 @@ repos: - id: forbid-submodules - id: mixed-line-ending - id: pretty-format-json - args: ["--autofix", "--no-sort-keys"] + args: [ "--autofix", "--no-sort-keys" ] - id: sort-simple-yaml - id: trailing-whitespace - - repo: https://github.com/lovesegfault/beautysh - rev: v6.2.1 + - repo: https://github.com/scop/pre-commit-shfmt + rev: v3.8.0-1 hooks: - - id: beautysh - additional_dependencies: - - setuptools + - id: shfmt - repo: https://github.com/shellcheck-py/shellcheck-py rev: v0.10.0.1 diff --git a/README.md b/README.md index 4e805fb..a86767b 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,21 @@ -# winapps +# WinApps -The winapps main project -Originally created by fmstrat https://github.com/Fmstrat/winapps/ +The WinApps main project, [originally created by Fmstrat](https://github.com/Fmstrat/winapps) -Run Windows apps such as Microsoft Office/Adobe in Linux (Ubuntu/Fedora) and GNOME/KDE as if they were a part of the native OS, including Nautilus integration for right clicking on files of specific mime types to open them. +Run Windows apps such as Microsoft Office/Adobe in Linux (Ubuntu/Fedora) and GNOME/KDE as if they were a part of the native OS, +including Nautilus integration for right-clicking on files of specific mime types to open them. ## How it works -WinApps was created as an easy, one command way to include apps running inside a VM (or on any RDP server) directly into GNOME as if they were native applications. WinApps works by: +WinApps was created as an easy, one-command way to include apps running inside a VM (or on any RDP server) directly into GNOME as if they were native applications. WinApps works by: - Running a Windows RDP server in a background VM container - Checking the RDP server for installed applications such as Microsoft Office - If those programs are installed, it creates shortcuts leveraging FreeRDP for both the CLI and the GNOME tray - Files in your home directory are accessible via the `\\tsclient\home` mount inside the VM -- You can right click on any files in your home directory to open with an application, too +- You can right-click on any files in your home directory to open with an application, too ## Currently supported applications @@ -23,7 +23,7 @@ WinApps was created as an easy, one command way to include apps running inside a It does this by: -1. Scanning your system for offically configured applications (below) +1. Scanning your system for the officially configured applications (below) 2. Scanning your system for any other EXE files with install records in the Windows Registry Any officially configured applications will have support for high-resolution icons and mime types for automatically detecting what files can be opened by each application. Any other detected executable files will leverage the icons pulled from the EXE. @@ -69,7 +69,7 @@ Note: The officially configured application list below is fueled by the communit Microsoft Publisher
(2016, 2019, o365) - Powershell + PowerShell Windows
(Full RDP session) @@ -79,28 +79,31 @@ Note: The officially configured application list below is fueled by the communit ## Installation -### Step 1: Set up a Windows Virtual Machine -The best solution for running a VM as a subsystem for WinApps would be docker. Docker allows to automize the install process and still uses kvm/qemu under the hood. We still provide the outdated KVM install instructions. +### Step 1: Set up a Windows virtual machine + +The best solution for running a VM as a subsystem for WinApps would be Docker. +Docker allows automizing the installation process and still uses KVM/QEMU under the hood. +We still provide the outdated KVM install instructions. To set up the VM for WinApps, follow this guide: -- [Creating a Virtual Machine with docker](docs/docker.md) -- [Creating a Virtual Machine in KVM (outdated)](docs/KVM.md) +- [Creating a virtual machine with Docker](docs/docker.md) +- [Creating a virtual machine in KVM (outdated)](docs/KVM.md) -If you already have a Virtual Machine or server you wish to use with WinApps, you will need to merge `install/RDPApps.reg` into the VM's Windows Registry. +If you already have a virtual machine or server you wish to use with WinApps, you will need to merge `install/RDPApps.reg` into the VM's Windows Registry. ### Step 2: Download the repo and prerequisites To get things going, use: ```bash -sudo apt install -y freerdp2-x11 +sudo apt install -y freerdp3-x11 git clone https://github.com/winapps-org/winapps.git cd winapps ``` > [!note] -> Ideally grab freerdp 3.0.0 or later, especially if you're having issues. -> You can find nightly builds here: https://github.com/FreeRDP/FreeRDP/wiki/Prebuilds +> Requires FreeRDP 3.0.0 or later. +> If not included in your distribution, you can download the Flatpak from here: https://github.com/FreeRDP/FreeRDP/wiki/Prebuilds ### Step 3: Creating your WinApps configuration file @@ -118,22 +121,23 @@ RDP_PASS="MyWindowsPassword" #FREERDP_COMMAND="xfreerdp" ``` -The username and password should be a full user account and password, such as the one created when setting up Windows or a domain user. It cannot be a user/PIN combination as those are not valid for RDP access. +The username and password should be a full user account and password, such as the one created when setting up Windows +or a domain user. It can't be a user/PIN combination as those aren't valid for RDP access. Options: -- When using a pre-existing non-KVM RDP server, you must use the `RDP_IP` to specify it's location -- If you are running a VM in KVM with NAT enabled, leave `RDP_IP` commented out and WinApps will auto-detect the right local IP +- When using a pre-existing non-KVM RDP server, you must use the `RDP_IP` to specify its location +- If you're running a VM in KVM with NAT enabled, leave `RDP_IP` commented out and WinApps will auto-detect the right local IP - For domain users, you can uncomment and change `RDP_DOMAIN` - On high-resolution (UHD) displays, you can set `RDP_SCALE` to the scale you would like [100|140|160|180] - To add flags to the FreeRDP call, such as `/audio-mode:1` to pass in a mic, use the `RDP_FLAGS` configuration option -- For multi-monitor setups, you can try enabling `MULTIMON`, however if you get a black screen (FreeRDP bug) you will need to revert back +- For multi-monitor setups, you can try enabling `MULTIMON`, however, if you get a black screen (FreeRDP bug) you will need to revert - If you enable `DEBUG`, a log will be created on each application start in `~/.local/share/winapps/winapps.log` -- If you are on a system, where the command for freeredp is not xfreerdp, change `FREERDP_COMMAND` to it. +- If you're on a system, where the command for freerdp is not xfreerdp, change `FREERDP_COMMAND` to it. ### Step 4: Run the WinApps installer -Lastly, check that FreeRDP can connect with: +Lastly, check if FreeRDP can connect with: ``` bin/winapps check @@ -149,7 +153,7 @@ If this step fails, try restarting the VM, or your problem could be related to: - Incorrect user credentials in `~/.config/winapps/winapps.conf` - Not merging `install/RDPApps.reg` into the VM -Then the final step is to run the installer which will prompt you for a system or user install: +Then the final step is to run the installer which will prompt you to a system or user install: ```bash ./installer.sh @@ -168,11 +172,13 @@ Adding applications with custom icons and mime types to the installer is easy. S - Re-run the installer - Submit a Pull Request to add it to WinApps officially -When running the installer, it will check for if any configured apps are installed, and if they are it will create the appropriate shortcuts on the host OS. +When running the installer, it will check for if any configured apps are installed, and if they are, +it will create the appropriate shortcuts on the host OS. ## Running applications manually -WinApps offers a manual mode for running applications that are not configured. This is completed with the `manual` flag. Executables that are in the path do not require full path definition. +WinApps offers a manual mode for running applications that aren't configured. This is completed with the `manual` flag. +Executables that are in the path don't require full path definition. ```bash ./bin/winapps manual "C:\my\directory\executableNotInPath.exe" @@ -181,7 +187,7 @@ WinApps offers a manual mode for running applications that are not configured. T ## Checking for new application support -The installer can be run multiple times, so simply run the below again and it will remove any current installations and update for the latest applications. +The installer can be run multiple times, so simply run the below again, and it will remove any current installations and update for the latest applications. ```bash ./installer.sh @@ -200,7 +206,7 @@ The following optional commands can be used to manage your application configura ./installer.sh --system --setupAllOfficiallySupportedApps # Configures all officially supported applications for the entire system ``` -## Shout outs +## Shout-outs - Some icons pulled from - Fluent UI React - Icons under [MIT License](https://github.com/Fmstrat/fluent-ui-react/blob/master/LICENSE.md) diff --git a/apps/access-o365-x86/icon.svg b/apps/access-o365-x86/icon.svg index 2e7240d..4b98d4f 100644 --- a/apps/access-o365-x86/icon.svg +++ b/apps/access-o365-x86/icon.svg @@ -1,3 +1,4 @@ - + diff --git a/apps/access-o365/icon.svg b/apps/access-o365/icon.svg index 2e7240d..4b98d4f 100644 --- a/apps/access-o365/icon.svg +++ b/apps/access-o365/icon.svg @@ -1,3 +1,4 @@ - + diff --git a/apps/access-x86/icon.svg b/apps/access-x86/icon.svg index 2e7240d..4b98d4f 100644 --- a/apps/access-x86/icon.svg +++ b/apps/access-x86/icon.svg @@ -1,3 +1,4 @@ - + diff --git a/apps/access/icon.svg b/apps/access/icon.svg index 2e7240d..4b98d4f 100644 --- a/apps/access/icon.svg +++ b/apps/access/icon.svg @@ -1,3 +1,4 @@ - + diff --git a/apps/acrobat-x-pro/icon.svg b/apps/acrobat-x-pro/icon.svg index 9c971f6..93f35fa 100644 --- a/apps/acrobat-x-pro/icon.svg +++ b/apps/acrobat-x-pro/icon.svg @@ -1,3 +1,4 @@ - + diff --git a/apps/adobe-cc/icon.svg b/apps/adobe-cc/icon.svg index 6c124a4..c4f106b 100644 --- a/apps/adobe-cc/icon.svg +++ b/apps/adobe-cc/icon.svg @@ -1 +1,3 @@ - + diff --git a/apps/aftereffects-cc/icon.svg b/apps/aftereffects-cc/icon.svg index 677803b..f807aaf 100644 --- a/apps/aftereffects-cc/icon.svg +++ b/apps/aftereffects-cc/icon.svg @@ -1 +1,3 @@ - + diff --git a/apps/audition-cc/icon.svg b/apps/audition-cc/icon.svg index af88949..5d216fd 100644 --- a/apps/audition-cc/icon.svg +++ b/apps/audition-cc/icon.svg @@ -1 +1,3 @@ - + diff --git a/apps/bridge-cc/icon.svg b/apps/bridge-cc/icon.svg index 6fd0faa..0392b1b 100644 --- a/apps/bridge-cc/icon.svg +++ b/apps/bridge-cc/icon.svg @@ -1 +1,4 @@ - + diff --git a/apps/bridge-cs6-x86/icon.svg b/apps/bridge-cs6-x86/icon.svg index 6fd0faa..0392b1b 100644 --- a/apps/bridge-cs6-x86/icon.svg +++ b/apps/bridge-cs6-x86/icon.svg @@ -1 +1,4 @@ - + diff --git a/apps/bridge-cs6/icon.svg b/apps/bridge-cs6/icon.svg index 6fd0faa..0392b1b 100644 --- a/apps/bridge-cs6/icon.svg +++ b/apps/bridge-cs6/icon.svg @@ -1 +1,4 @@ - + diff --git a/apps/cmd/icon.svg b/apps/cmd/icon.svg index db435c4..2a8f304 100644 --- a/apps/cmd/icon.svg +++ b/apps/cmd/icon.svg @@ -1,3 +1,3 @@ - + diff --git a/apps/excel-o365-x86/icon.svg b/apps/excel-o365-x86/icon.svg index 2992c1f..b6c35bb 100644 --- a/apps/excel-o365-x86/icon.svg +++ b/apps/excel-o365-x86/icon.svg @@ -1 +1,3 @@ - + + + diff --git a/apps/excel-o365/icon.svg b/apps/excel-o365/icon.svg index 2992c1f..b6c35bb 100644 --- a/apps/excel-o365/icon.svg +++ b/apps/excel-o365/icon.svg @@ -1 +1,3 @@ - + + + diff --git a/apps/excel-x86/icon.svg b/apps/excel-x86/icon.svg index 2992c1f..b6c35bb 100644 --- a/apps/excel-x86/icon.svg +++ b/apps/excel-x86/icon.svg @@ -1 +1,3 @@ - + + + diff --git a/apps/excel/icon.svg b/apps/excel/icon.svg index 2992c1f..b6c35bb 100644 --- a/apps/excel/icon.svg +++ b/apps/excel/icon.svg @@ -1 +1,3 @@ - + + + diff --git a/apps/explorer/icon.svg b/apps/explorer/icon.svg index 4f1252f..bcc6fa0 100644 --- a/apps/explorer/icon.svg +++ b/apps/explorer/icon.svg @@ -1 +1,2 @@ - + + diff --git a/apps/illustrator-cc/icon.svg b/apps/illustrator-cc/icon.svg index 21d31b3..e171bc7 100644 --- a/apps/illustrator-cc/icon.svg +++ b/apps/illustrator-cc/icon.svg @@ -1 +1,3 @@ - + diff --git a/apps/indesign-cc/icon.svg b/apps/indesign-cc/icon.svg index ceaa431..bf734fb 100644 --- a/apps/indesign-cc/icon.svg +++ b/apps/indesign-cc/icon.svg @@ -1 +1,3 @@ - + diff --git a/apps/lightroom-cc/icon.svg b/apps/lightroom-cc/icon.svg index 6d10ba7..fa3137e 100644 --- a/apps/lightroom-cc/icon.svg +++ b/apps/lightroom-cc/icon.svg @@ -1 +1,3 @@ - + diff --git a/apps/outlook-o365-x86/icon.svg b/apps/outlook-o365-x86/icon.svg index a459409..1c09e1a 100644 --- a/apps/outlook-o365-x86/icon.svg +++ b/apps/outlook-o365-x86/icon.svg @@ -1,3 +1,3 @@ - + diff --git a/apps/outlook-o365/icon.svg b/apps/outlook-o365/icon.svg index a459409..1c09e1a 100644 --- a/apps/outlook-o365/icon.svg +++ b/apps/outlook-o365/icon.svg @@ -1,3 +1,3 @@ - + diff --git a/apps/outlook-x86/icon.svg b/apps/outlook-x86/icon.svg index a459409..1c09e1a 100644 --- a/apps/outlook-x86/icon.svg +++ b/apps/outlook-x86/icon.svg @@ -1,3 +1,3 @@ - + diff --git a/apps/outlook/icon.svg b/apps/outlook/icon.svg index a459409..1c09e1a 100644 --- a/apps/outlook/icon.svg +++ b/apps/outlook/icon.svg @@ -1,3 +1,3 @@ - + diff --git a/apps/photoshop-cc/icon.svg b/apps/photoshop-cc/icon.svg index 9565f6d..eb0b520 100644 --- a/apps/photoshop-cc/icon.svg +++ b/apps/photoshop-cc/icon.svg @@ -1 +1,4 @@ - + diff --git a/apps/photoshop-cs6-x86/icon.svg b/apps/photoshop-cs6-x86/icon.svg index 9565f6d..eb0b520 100644 --- a/apps/photoshop-cs6-x86/icon.svg +++ b/apps/photoshop-cs6-x86/icon.svg @@ -1 +1,4 @@ - + diff --git a/apps/photoshop-cs6/icon.svg b/apps/photoshop-cs6/icon.svg index 9565f6d..eb0b520 100644 --- a/apps/photoshop-cs6/icon.svg +++ b/apps/photoshop-cs6/icon.svg @@ -1 +1,4 @@ - + diff --git a/apps/powershell/icon.svg b/apps/powershell/icon.svg index a423aca..b2b600f 100644 --- a/apps/powershell/icon.svg +++ b/apps/powershell/icon.svg @@ -1 +1,3 @@ - + + + diff --git a/apps/publisher-o365-x86/icon.svg b/apps/publisher-o365-x86/icon.svg index 82b310e..2ba2801 100644 --- a/apps/publisher-o365-x86/icon.svg +++ b/apps/publisher-o365-x86/icon.svg @@ -1,3 +1,3 @@ - + diff --git a/apps/publisher-o365/icon.svg b/apps/publisher-o365/icon.svg index 82b310e..2ba2801 100644 --- a/apps/publisher-o365/icon.svg +++ b/apps/publisher-o365/icon.svg @@ -1,3 +1,3 @@ - + diff --git a/apps/publisher-x86/icon.svg b/apps/publisher-x86/icon.svg index 82b310e..2ba2801 100644 --- a/apps/publisher-x86/icon.svg +++ b/apps/publisher-x86/icon.svg @@ -1,3 +1,3 @@ - + diff --git a/apps/publisher/icon.svg b/apps/publisher/icon.svg index 82b310e..2ba2801 100644 --- a/apps/publisher/icon.svg +++ b/apps/publisher/icon.svg @@ -1,3 +1,3 @@ - + diff --git a/apps/word-o365-x86/icon.svg b/apps/word-o365-x86/icon.svg index 643aaf4..145f733 100644 --- a/apps/word-o365-x86/icon.svg +++ b/apps/word-o365-x86/icon.svg @@ -1,3 +1,4 @@ - + diff --git a/apps/word-o365/icon.svg b/apps/word-o365/icon.svg index 643aaf4..145f733 100644 --- a/apps/word-o365/icon.svg +++ b/apps/word-o365/icon.svg @@ -1,3 +1,4 @@ - + diff --git a/apps/word-x86/icon.svg b/apps/word-x86/icon.svg index 643aaf4..145f733 100644 --- a/apps/word-x86/icon.svg +++ b/apps/word-x86/icon.svg @@ -1,3 +1,4 @@ - + diff --git a/apps/word/icon.svg b/apps/word/icon.svg index 643aaf4..145f733 100644 --- a/apps/word/icon.svg +++ b/apps/word/icon.svg @@ -1,3 +1,4 @@ - + diff --git a/docs/KVM.md b/docs/KVM.md index ea65b27..e2e1e15 100644 --- a/docs/KVM.md +++ b/docs/KVM.md @@ -1,21 +1,30 @@ # Creating a Virtual Machine in KVM -This step-by-step guide will take you through setting up a CPU and memory efficient virtual machine to use with WinApps leveraging KVM, an open-source virtualization software contained in most linux distributions. + +This step-by-step guide will take you through setting up a CPU and memory efficient virtual machine +to use with WinApps leveraging KVM, an open-source virtualization software contained in most Linux distributions. ## Install KVM + First up, you must install KVM and the Virtual Machine Manager. By installing `virt-manager`, you will get everything you need for your distribution: + ```bash -sudo apt-get install -y virt-manager +sudo apt install -y virt-manager ``` ## Download the Windows Professional and KVM VirtIO drivers -You will need Windows 10 Professional (or Enterprise or Server) to run RDP apps, Windows 10 Home will not suffice. You will also need drivers for VirtIO to ensure the best performance and lowest overhead for your system. You can download these at the following links. + +You will need Windows 10 Professional (or Enterprise or Server) to run RDP apps, Windows 10 Home will not suffice. +You will also need drivers for VirtIO to ensure the best performance and the lowest overhead for your system. +You can download these at the following links: Windows 10 ISO: https://www.microsoft.com/en-us/software-download/windows10ISO KVM VirtIO drivers (for all distros): https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.iso ## Create your virtual machine -The following guide will take you through the setup. If you are an expert user, you may wish to: + +The following guide will take you through the setup. If you're an expert user, you may wish to: + - [Define a VM from XML (may not work on all systems)](#define-a-vm-from-xml) - [Run KVM in user mode](#run-kvm-in-user-mode) @@ -39,11 +48,13 @@ Now select the location of your Windows 10 ISO, and `Automatically detect` the i ![](kvm/04.png) -Set your memory and CPUs. We recommend `2` CPUs and `4096MB` for memory. We will be using a Memory Ballooning service, meaning 4096 is the maximum amount of memory the VM will ever use, but will not use this amount except when it is needed. +Set your memory and CPUs. We recommend `2` CPUs and `4096MB` for memory. We will be using a Memory Ballooning service, +meaning 4096 is the maximum amount of memory the VM will ever use, but will not use this amount except when it is needed. ![](kvm/05.png) -Choose your virtual disk size, keep in mind this is the maximum size the disk will grow to, but it will not take up this space until it needs it. +Choose your virtual disk size, keep in mind this is the maximum size the disk will grow to, +but it will not take up this space until it needs it. ![](kvm/06.png) @@ -58,12 +69,14 @@ After clicking `Finish`, ensure under CPU that `Copy host CPU configuration` is ![](kvm/08.png) Next, go to the `XML` tab, and edit the `` section to contain: + ```xml ``` + Then `Apply`. This will drastically reduce idle CPU usage (from ~25% to ~3%). ![](kvm/09.png) @@ -84,30 +97,35 @@ For the NIC, set the `Device model` to `virtio`. ![](kvm/13.png) -Click the `Add Hardware` button in the lower right, and choose `Storage`. For `Device type`, select `CDROM device` and choose the VirtIO driver ISO you downloaded earlier. This will give the Windows 10 Installer access to drivers during the install process. Now click `Finish` to add the new CDROM device. +Click the `Add Hardware` button in the lower right, and choose `Storage`. For `Device type`, select `CDROM device` +and choose the VirtIO driver ISO you downloaded earlier. This will give the Windows 10 Installer access +to drivers during the installation process. Now click `Finish` to add the new CD-ROM device. ![](kvm/14.png) -You are now ready to click `Begin Installation` +You're now ready to click `Begin Installation` ![](kvm/15.png) Now move on to installing the virtual machine. ## Install the virtual machine + From here out you will install Windows 10 Professional as you would on any other machine. ![](kvm/16.png) -Once you get to the point of selecting the location for installation, you will see there are no disks available. This is because we need to load the VirtIO driver. Select `Load driver`. +Once you get to the point of selecting the location for installation, you will see there are no disks available. +This is because we need to load the VirtIO driver. Select `Load driver`. ![](kvm/17.png) -The installer will then ask you to specify where the driver is located. Select the `E:\` drive or whichever drive the VirtIO driver ISO is located on. +The installer will then ask you to specify where the driver is located. Select the `E:\` drive +or whichever drive the VirtIO driver ISO is located on. ![](kvm/18.png) -Choose the appropriate driver for the OS you have selected, which is most likely the `w10` driver for Windows 10. +Choose the appropriate driver for the OS you've selected, which is most likely the `w10` driver for Windows 10. ![](kvm/19.png) @@ -115,11 +133,12 @@ You will now see a disk you can select for the installation. ![](kvm/20.png) -Windows will begin to install, and you will likely need to reboot the VM a number times during this process. +Windows will begin to install, and you will likely need to reboot the VM a number of times during this process. ![](kvm/21.png) -At some point, you will come to a network screen. This is because the VirtIO drivers for the network have not yet been loaded. Simply click `I don't have internet`. +At some point, you will come to a network screen. This is because the VirtIO drivers +for the network haven't yet been loaded. Simply click `I don't have internet`. ![](kvm/22.png) @@ -127,31 +146,37 @@ It will confirm your choice, so just choose `Continue with limited setup`. ![](kvm/23.png) -After you get into Windows and login with the user you created during the install. Open up `Explorer` and navigate the `E:\` drive or wherever the VirtIO driver ISO is mounted. Double click the `virt-win-gt-64.exe` file to launch the VirtIO driver installer. +After you get into Windows and login with the user you created during the installation. Open `Explorer` +and navigate the `E:\` drive or wherever the VirtIO driver ISO is mounted. Double-click the `virt-win-gt-64.exe` file +to launch the VirtIO driver installer. ![](kvm/24.png) -Leave everything as default and click `Next` through the installer. This will install device drivers as well as the Memory Ballooning service. +Leave everything as default and click `Next` through the installer. This will install device drivers as well as +the Memory Ballooning service. ![](kvm/25.png) -Once you finish the driver install, you will need to make some registry changes to enable RDP Applications to run on the system. Start by downloading the [RDPApps.reg](/install/RDPApps.reg) file, right clicking on the `Raw` button, and clicking on `Save target as`. +Once you finish the driver install, you will need to make some registry changes to enable RDP Applications +to run on the system. Start by downloading the [RDPApps.reg](/install/RDPApps.reg) file, +right-clicking on the `Raw` button, and clicking on `Save target as`. ![](kvm/26.png) -Once you have downloaded the registry file, right click on it, and choose `Merge`, then accept any confirmations along the way. +Once you've downloaded the registry file, right-click on it, and choose `Merge`, then accept any confirmations along the way. ![](kvm/27.png) -Next up, we need to rename the VM so that WinApps can locate it. Go to the start menu and type `About` to bring up the `About your PC` settings. +Next up, we need to rename the VM so that WinApps can locate it. Go to the start menu and type `About` +to bring up the `About your PC` settings. ![](kvm/28.png) -Scroll down and click on `Rename this PC` +Scroll down and click on `Rename this PC`. ![](kvm/29.png) -Rename to `RDPWindows`, and then `Next`, but **do not** restart. +Rename to `RDPWindows`, and then `Next`, but **don't** restart. ![](kvm/30.png) @@ -159,36 +184,49 @@ Lastly, scroll down to `Remote Desktop`, and toggle `Enable Remote Desktop` on, ![](kvm/31.png) -At this point you will need to restart and you have completed your setup. +At this point, you will need to restart, and you've completed your setup. -Rather than restart you can go right ahead and install other applications like Microsoft Office or Adobe CC that could be used through WinApps. +Rather than restart, you can go right ahead and install other applications like Microsoft Office or Adobe CC +that could be used through WinApps. -You may also wish to install the [Spice Guest Tools](https://www.spice-space.org/download/windows/spice-guest-tools/spice-guest-tools-latest.exe) inside the VM which enables features like auto-desktop resize and cut-and-paste when using `virt-manager`. As WinApps uses RDP, this is not necessary if you do not plan to access the machine via `virt-manager`. +You may also wish to install +the [Spice Guest Tools](https://www.spice-space.org/download/windows/spice-guest-tools/spice-guest-tools-latest.exe) +inside the VM which enables features like auto-desktop resize and cut-and-paste when using `virt-manager`. +As WinApps uses RDP, this is unnecessary if you don't plan to access the machine via `virt-manager`. -Once you are finished, restart the VM, but do not log in. Simply close the VM viewer, and close the Virtual Machine Manager. +Once you're finished, restart the VM, but don't log in. Simply close the VM viewer, and close the Virtual Machine Manager. ## Expert installs ### Define a VM from XML + This expert guide for XML imports is specific to Ubuntu 20.04 and may not work on all hardware platforms. -You can refer to the [KVM](https://www.linux-kvm.org) documentation for specifics, but the first thing you need to do is set up a Virtual Machine running Windows 10 Professional (or any version that supports RDP). First, install KVM: +You can refer to the [KVM](https://www.linux-kvm.org) documentation for specifics, but the first thing you need to do is +set up a Virtual Machine running Windows 10 Professional (or any version that supports RDP). First, install KVM: + ``` bash -sudo apt-get install -y virt-manager +sudo apt install -y virt-manager ``` -Now, copy your Windows ISO and VirtIO iso (links to download in the main guide) into the folder and update the `kvm/RDPWindows.xml` appropriately. + +Now, copy your Windows ISO and VirtIO iso (links to download in the main guide) into the folder +and update the `kvm/RDPWindows.xml` appropriately. Next, define a VM called RDPWindows from the sample XML file with: + ``` bash virsh define kvm/RDPWindows.xml virsh autostart RDPWindows ``` + You should then open the VMs properties in `virt-manager` and ensure that under CPU `Copy host CPU configuration` is selected. -Boot it up, install windows, and then [Install the virtual machine](#install-the-virtual-machine). +Boot it up, install Windows, and then [Install the virtual machine](#install-the-virtual-machine). ### Run KVM in user mode + Now set up KVM to run as your user instead of root and allow it through AppArmor (for Ubuntu 20.04 and above): + ``` bash sudo sed -i "s/#user = "root"/user = "$(id -un)"/g" /etc/libvirt/qemu.conf sudo sed -i "s/#group = "root"/group = "$(id -gn)"/g" /etc/libvirt/qemu.conf @@ -197,4 +235,5 @@ sudo usermod -a -G libvirt $(id -un) sudo systemctl restart libvirtd sudo ln -s /etc/apparmor.d/usr.sbin.libvirtd /etc/apparmor.d/disable/ ``` + You will likely need to reboot to ensure your current shell is added to the group. diff --git a/docs/docker.md b/docs/docker.md index 501e49b..901c967 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -1,26 +1,32 @@ -# Docker +# Creating a Virtual Machine in Docker -## Why docker? +## Why Docker? -While working with `virsh` is completely fine for winapps, you have to set up and optimize you vm manually. Docker on the other hand sets up most of the stuff automatically and also makes the VM highly portable between Linux distros. +While working with `virsh` is completely fine for WinApps, you have to set up and optimize your VM manually. +Docker, on the other hand, sets up most of the stuff automatically and makes the VM highly portable between Linux distros. # Requirements -Since Docker manages the dependencies of the container automatically you only need to install Docker itself. +Since Docker manages the dependencies of the container automatically, you only need to install Docker itself. -You can try using Podman too because of their faster container startup times, but note that Podman and Docker are not always fully interchangeable. In case you want to follow this guide using podman, you will have to install the `docker` CLI to be able to run `docker compose` commands. You'll also have to enable the Podman socket. Refer to the podman docs for how to do that. +You can try using Podman too because of their faster container startup times, +but note that Podman and Docker aren't always fully interchangeable. In case you want to follow this guide using Podman, +you will have to install the `docker` CLI to be able to run `docker compose` commands. +You will also have to enable the Podman socket. Refer to the Podman docs for how to do that. See: + - [Podman installation docs](https://podman.io/docs/installation) - [Docker installation docs](https://docs.docker.com/engine/install) - [Using `docker compose` with Podman](https://www.redhat.com/sysadmin/podman-docker-compose) (slightly outdated) > [!NOTE] -> This will only work on Linux systems since some kernel interfaces (like KVM) are needed by the VM. Because of this performance can vary depending on kernel version (newer will likely perform better). +> This will only work on Linux systems since the VM needs some kernel interfaces (like KVM). Because of this, +> performance can vary depending on kernel version (newer will likely perform better). -# Setup docker container +# Setup Docker Container -The easiest way to set up a Windows VM is by using docker compose. A compose file that looks like this is already shipped with winapps: +The easiest way to set up a Windows VM is by using docker compose. A compose file that looks like this is already shipped with WinApps: ```yaml name: "winapps" @@ -47,35 +53,42 @@ services: - data:/storage ``` -Now you can tune the ram/usage by changing `RAM_SIZE` & `CPU_CORES`. You can also specify the windows versions you want to use. You might also want to take a look at the [repo of the Docker image](https://github.com/dockur/windows) for further information. +Now you can tune the RAM/usage by changing `RAM_SIZE` & `CPU_CORES`. You can also specify +the Windows versions you want to use. You might also want to take a look at the [repo of the Docker image](https://github.com/dockur/windows) for further information. This compose file uses Windows 11 by default. You can use Windows 10 by changing the `VERSION` to `tiny10`. > [!NOTE] -> We use a stripped-down Windows installation by default. This is recommended, but you can still opt for stock windows by changing the version to one of the versions listed in the README of the images repository linked above. +> We use a stripped-down Windows installation by default. This is recommended, +> but you can still opt for stock Windows by changing the version to one of the versions listed in +> the README of the images repository linked above. > [!NOTE] -> Older versions than Windows 10 are not officially supported by us. However they might still work with some additional tuning. +> We don't officially support older versions than Windows 10. However, they might still work with some additional tuning. You can now just run: + ```shell docker compose up -d ``` + to run the VM in the background. -After this just open http://127.0.0.1:8006 in your web browser and wait for the Windows installation to finish. +After this, just open http://127.0.0.1:8006 in your web browser and wait for the Windows installation to finish. > [!WARNING] -> Make sure to change the `RDP_IP` in your winapps config to `127.0.0.1`. +> Make sure to change the `RDP_IP` in your WinApps config to `127.0.0.1`. -Now you should be ready to go and try to connect to your VM with winapps. +Now you should be ready to go and try to connect to your VM with WinApps. + +For stopping the VM, just use: -For stopping the VM just use: ```shell docker compose stop ``` -For starting again afterwards use: +For starting again afterward, use: + ```shell docker compose start ``` diff --git a/icons/windows.svg b/icons/windows.svg index 6296a2a..ea5b408 100644 --- a/icons/windows.svg +++ b/icons/windows.svg @@ -1,3 +1,3 @@ - + diff --git a/kvm/RDPWindows.xml b/kvm/RDPWindows.xml index 4a7e227..cfd5a08 100644 --- a/kvm/RDPWindows.xml +++ b/kvm/RDPWindows.xml @@ -1,210 +1,210 @@ - RDPWindows - 50f121b4-93e7-46b5-b302-902d022dfa9c - - - - - - 4194304 - 1298432 - 2 - - /machine - - - hvm - - - - - - - - - - - - - Haswell-noTSX-IBRS - Intel - - - - - - - - - - - - - - - - - - - - - - - - - - - destroy - restart - destroy - - - - - - /usr/bin/qemu-system-x86_64 - - - - - - - - -
- - - - - - - - -
- - - - - - - - -
- - - -
- - - -
- - - - - - - - -
- - - - - -
- - - - - -
- - - - - -
- - - - - -
- - - - - -
- - - -
- - - - - - - -
- - - - - - - - - - - - - - - - -
- - - -
- - - - - - - - - - - - - -
- -