marcel/winapps
1
0
Fork 0
mirror of https://github.com/winapps-org/winapps.git synced 2025-06-23 06:33:02 +02:00
Code Issues Packages Projects Releases Wiki Activity

Updated README.md

Browse Source
This commit is contained in:
Rohan Barar 2024-07-16 12:04:25 +10:00
parent a3ed167291
commit 75c790fd0d
3 changed files with 136 additions and 166 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

285
README.md
View File

@ -1,114 +1,116 @@
# WinApps # WinApps
*The WinApps project, forked from Fmstrat's [original repository](https://github.com/Fmstrat/winapps).*
The WinApps main project, [originally created by Fmstrat](https://github.com/Fmstrat/winapps) 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` or `GNOME`, integrated seamlessly as if they were native to the OS.
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, <img src="demo/demo.gif" width=1000 alt="WinApps Demonstration Animation.">
including Nautilus integration for right-clicking on files of specific mime types to open them.
<img src="demo/demo.gif" width=1000> ## Underlying Mechanism
WinApps works by:
1. Running Windows in a `Docker` or `libvirt + KVM/QEMU` virtual machine (deprecated).
2. Querying Windows for all installed applications.
3. Creating shortcuts to selected Windows applications on the host GNU/Linux OS.
4. Using [`FreeRDP`](https://www.freerdp.com/) as a backend to seamlessly render Windows applications alongside GNU/Linux applications.
## How it works ## 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.
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: ## Supported Applications
**WinApps supports <u>*ALL*</u> Windows applications.**
- Running a Windows RDP server in a background VM container Universal application support is achieved by:
- Checking the RDP server for installed applications such as Microsoft Office 1. Scanning Windows for any officially supported applications (list below).
- If those programs are installed, it creates shortcuts leveraging FreeRDP for both the CLI and the GNOME tray 2. Scanning Windows for any other `.exe` files listed within the Windows Registry.
- 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
## Currently supported applications Officially supported applications benefit from high-resolution icons and pre-populated MIME types. This enables file managers to determine which Windows applications should open files based on file extensions. Icons for other detected applications are pulled from `.exe` files.
### WinApps supports **_ANY_** installed application on your system. Contributing to the list of supported applications is encouraged through submission of pull requests! Please help us grow the WinApps community.
It does this by: *Please note that the provided list of officially supported applications is community-driven. As such, some applications may not be tested and verified by the WinApps team.*
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.
Note: The officially configured application list below is fueled by the community, and therefore some apps may be untested by the WinApps team.
### Officially Supported Applications
<table cellpadding="10" cellspacing="0" border="0"> <table cellpadding="10" cellspacing="0" border="0">
<tr> <tr>
<td><img src="apps/acrobat-x-pro/icon.svg" width="100"></td><td>Adobe Acrobat Pro<br>(X)</td> <td><img src="apps/acrobat-x-pro/icon.svg" width="100"></td><td>Adobe Acrobat Pro<br>(X)</td>
<td><img src="apps/acrobat-reader-dc/icon.svg" width="100"></td><td>Adobe Acrobat Reader<br>(DC)</td> <td><img src="apps/aftereffects-cc/icon.svg" width="100"></td><td>Adobe After Effects<br>(CC)</td>
</tr> </tr>
<tr> <tr>
<td><img src="apps/aftereffects-cc/icon.svg" width="100"></td><td>Adobe After Effects<br>(CC)</td> <td><img src="apps/audition-cc/icon.svg" width="100"></td><td>Adobe Audition<br>(CC)</td>
<td><img src="apps/audition-cc/icon.svg" width="100"></td><td>Adobe Audition<br>(CC)</td> <td><img src="apps/bridge-cs6/icon.svg" width="100"></td><td>Adobe Bridge<br>(CS6, CC)</td>
</tr> </tr>
<tr> <tr>
<td><img src="apps/bridge-cs6/icon.svg" width="100"></td><td>Adobe Bridge<br>(CS6, CC)</td> <td><img src="apps/adobe-cc/icon.svg" width="100"></td><td>Adobe Creative Cloud<br>(CC)</td>
<td><img src="apps/adobe-cc/icon.svg" width="100"></td><td>Adobe Creative Cloud<br>(CC)</td> <td><img src="apps/illustrator-cc/icon.svg" width="100"></td><td>Adobe Illustrator<br>(CC)</td>
</tr> </tr>
<tr> <tr>
<td><img src="apps/illustrator-cc/icon.svg" width="100"></td><td>Adobe Illustrator<br>(CC)</td> <td><img src="apps/indesign-cc/icon.svg" width="100"></td><td>Adobe InDesign<br>(CC)</td>
<td><img src="apps/indesign-cc/icon.svg" width="100"></td><td>Adobe InDesign<br>(CC)</td> <td><img src="apps/lightroom-cc/icon.svg" width="100"></td><td>Adobe Lightroom<br>(CC)</td>
</tr> </tr>
<tr> <tr>
<td><img src="apps/lightroom-cc/icon.svg" width="100"></td><td>Adobe Lightroom<br>(CC)</td> <td><img src="apps/cmd/icon.svg" width="100"></td><td>Command Prompt<br>(cmd.exe)</td>
<td><img src="apps/cmd/icon.svg" width="100"></td><td>Command Prompt<br>(cmd.exe)</td> <td><img src="apps/explorer/icon.svg" width="100"></td><td>Explorer<br>(File Manager)</td>
</tr> </tr>
<tr> <tr>
<td><img src="apps/explorer/icon.svg" width="100"></td><td>Explorer<br>(File Manager)</td> <td><img src="apps/iexplorer/icon.svg" width="100"></td><td>Internet Explorer<br>(11)</td>
<td><img src="apps/iexplorer/icon.svg" width="100"></td><td>Internet Explorer<br>(11)</td> <td><img src="apps/access/icon.svg" width="100"></td><td>Microsoft Access<br>(2016, 2019, o365)</td>
</tr> </tr>
<tr> <tr>
<td><img src="apps/access/icon.svg" width="100"></td><td>Microsoft Access<br>(2016, 2019, o365)</td> <td><img src="apps/excel/icon.svg" width="100"></td><td>Microsoft Excel<br>(2016, 2019, o365)</td>
<td><img src="apps/excel/icon.svg" width="100"></td><td>Microsoft Excel<br>(2016, 2019, o365)</td> <td><img src="apps/word/icon.svg" width="100"></td><td>Microsoft Word<br>(2016, 2019, o365)</td>
</tr> </tr>
<tr> <tr>
<td><img src="apps/word/icon.svg" width="100"></td><td>Microsoft Word<br>(2016, 2019, o365)</td> <td><img src="apps/onenote/icon.svg" width="100"></td><td>Microsoft OneNote<br>(2016, 2019, o365)</td>
<td><img src="apps/onenote/icon.svg" width="100"></td><td>Microsoft OneNote<br>(2016, 2019, o365)</td> <td><img src="apps/outlook/icon.svg" width="100"></td><td>Microsoft Outlook<br>(2016, 2019, o365)</td>
</tr> </tr>
<tr> <tr>
<td><img src="apps/outlook/icon.svg" width="100"></td><td>Microsoft Outlook<br>(2016, 2019, o365)</td> <td><img src="apps/powerpoint/icon.svg" width="100"></td><td>Microsoft PowerPoint<br>(2016, 2019, o365)</td>
<td><img src="apps/powerpoint/icon.svg" width="100"></td><td>Microsoft PowerPoint<br>(2016, 2019, o365)</td> <td><img src="apps/publisher/icon.svg" width="100"></td><td>Microsoft Publisher<br>(2016, 2019, o365)</td>
</tr> </tr>
<tr> <tr>
<td><img src="apps/publisher/icon.svg" width="100"></td><td>Microsoft Publisher<br>(2016, 2019, o365)</td> <td><img src="apps/powershell/icon.svg" width="100"></td><td>PowerShell</td>
<td><img src="apps/powershell/icon.svg" width="100"></td><td>PowerShell</td> <td><img src="icons/windows.svg" width="100"></td><td>Windows<br>(Full RDP session)</td>
</tr> </tr>
<tr>
<td><img src="icons/windows.svg" width="100"></td><td>Windows<br>(Full RDP session)</td>
<td>&nbsp;</td><td>&nbsp;</td>
</tr>
</table> </table>
## Installation ## Installation
### Step 1: Configure a Windows VM
The optimal choice for running a Windows VM as a subsystem for WinApps is `Docker`. `Docker` facilitates automated installation processes while leveraging a `KVM/QEMU` backend. Despite continuing to provide documentation for configuring a Windows VM using `libvirt` and `virt-manager`, this method is now considered deprecated.
### Step 1: Set up a Windows virtual machine The following guides are available:
- [Creating a Windows VM with `Docker`](docs/docker.md)
- [Creating a Windows VM with `virt-manager`](docs/KVM.md) (Deprecated)
The best solution for running a VM as a subsystem for WinApps would be Docker. If you already have a Windows VM or server you wish to use with WinApps, you will need to merge `install/RDPApps.reg` into the Windows Registry.
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) ### Step 2: Clone WinApps Repository and Dependencies
- [Creating a virtual machine in KVM (outdated)](docs/KVM.md) 1. Clone the WinApps GitHub repository.
```bash
git clone https://github.com/winapps-org/winapps.git && cd winapps
```
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. 2. Install the required dependencies.
- Debian/Ubuntu:
```bash
sudo apt install -y dialog freerdp3-x11
```
- Fedora/RHEL:
```bash
sudo dnf install -y dialog freerdp
```
- Arch Linux:
```bash
sudo pacman -Syu --needed -y dialog freerdp
```
- Gentoo Linux:
```bash
sudo emerge --ask=n sys-libs/dialog net-misc/freerdp:3
```
### Step 2: Download the repo and prerequisites > WinApps requires `FreeRDP v3` or later. If not available for your distribution through your package manager, you can install the [Flatpak](https://github.com/FreeRDP/FreeRDP/wiki/Prebuilds).
To get things going, use:
```bash
sudo apt install -y freerdp3-x11
git clone https://github.com/winapps-org/winapps.git
cd winapps
```
> [!note]
> 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
You will need to create a `~/.config/winapps/winapps.conf` configuration file with the following information in it:
### Step 3: Create a WinApps Configuration File
Create a configuration file at `~/.config/winapps/winapps.conf` containing the following:
```bash ```bash
RDP_USER="MyWindowsUser" RDP_USER="MyWindowsUser"
RDP_PASS="MyWindowsPassword" RDP_PASS="MyWindowsPassword"
@ -121,95 +123,52 @@ RDP_PASS="MyWindowsPassword"
#FREERDP_COMMAND="xfreerdp" #FREERDP_COMMAND="xfreerdp"
``` ```
The username and password should be a full user account and password, such as the one created when setting up Windows `RDP_USER` and `RDP_PASS` must correspond to a complete Windows user account and password, such as those created during Windows setup or for a domain user. User/PIN combinations are not valid for RDP access.
or a domain user. It can't be a user/PIN combination as those aren't valid for RDP access.
Options: #### Configuration Options Explained
- When using a pre-existing non-KVM RDP server, you must use `RDP_IP` to specify the location of the Windows server.
- When using a pre-existing non-KVM RDP server, you must use the `RDP_IP` to specify its location - If running a Windows VM in KVM with NAT enabled, leave `RDP_IP` commented out and WinApps will auto-detect the local IP address for the VM.
- 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`.
- 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 to use [100|140|160|180].
- 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 microphone, uncomment and use the `RDP_FLAGS` configuration option.
- 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`. A FreeRDP bug may result in a black screen however, in which case you should revert this change.
- 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 enable `DEBUG`, a log will be created on each application start in `~/.local/share/winapps/winapps.log`
- If you're on a system, where the command for freerdp is not xfreerdp, change `FREERDP_COMMAND` to it. - If using a system on which the FreeRDP command is not `xfreerdp`, the correct command can be specified using `FREERDP_COMMAND`.
### Step 4: Run the WinApps installer
Lastly, check if FreeRDP can connect with:
```
bin/winapps check
```
You will see output from FreeRDP, as well as potentially have to accept the initial certificate. After that, a Windows Explorer window should pop up. You can close this window and press `Ctrl-C` to cancel out of FreeRDP.
If this step fails, try restarting the VM, or your problem could be related to:
- You need to accept the security cert the first time you connect (with 'check')
- Not enabling RDP in the Windows VM
- Not being able to connect to the IP of the VM
- 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 to a system or user install:
### Step 4: Run the WinApps Installer
Run the WinApps installer.
```bash ```bash
./installer.sh ./installer.sh
``` ```
This will take you through the following process: A list of supported additional arguments can be accessed by running `./installer.sh --help`.
<img src="demo/installer.gif" width=1000> <img src="demo/installer.gif" width=1000>
## Adding pre-defined applications ## 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:
1. Modify the name and variables to reflect the appropriate/desired values for your application.
2. Replace `icon.svg` with an SVG for your application (ensuring the icon is appropriately licensed).
3. Remove and reinstall WinApps.
4. (Optional, but strongly encouraged) Submit a pull request to add your application to WinApps as an officially supported application once you have tested your configuration files to verify functionality.
Adding applications with custom icons and mime types to the installer is easy. Simply copy one of the application configurations in the `apps` folder, and: ## Running Applications Manually
WinApps offers a manual mode for running applications that were not configured by the WinApps installer. This is completed with the `manual` flag. Executables that are in the Windows PATH do not require full path definition.
- Edit the variables for the application
- Replace the `icon.svg` with an SVG for the application (appropriately licensed)
- 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.
## Running applications manually
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 ```bash
./bin/winapps manual "C:\my\directory\executableNotInPath.exe" ./bin/winapps manual "C:\my\directory\executableNotInPath.exe"
./bin/winapps manual executableInPath.exe ./bin/winapps manual executableInPath.exe
``` ```
## Checking for new application support ## Updating WinApps
The installer can be run multiple times. To update your installation of WinApps:
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. 1. Run the WinApps installer to remove WinApps from your system.
2. Pull the latest changes from the WinApps GitHub repository.
```bash 3. Re-install WinApps using the WinApps installer.
./installer.sh
```
## Optional installer command line arguments
The following optional commands can be used to manage your application configurations without prompts:
```bash
./installer.sh --user # Configure applications for the current user
./installer.sh --system # Configure applications for the entire system
./installer.sh --user --uninstall # Remove all configured applications for the current user
./installer.sh --system --uninstall # Remove all configured applications for the entire system
./installer.sh --user --setupAllOfficiallySupportedApps # Configures all officially supported applications for the current user
./installer.sh --system --setupAllOfficiallySupportedApps # Configures all officially supported applications for the entire system
```
## Shout-outs ## Shout-outs
- Some icons used for the officially supported applications were sourced from:
- Some icons pulled from - Fluent UI React - Icons under [MIT License](https://github.com/Fmstrat/fluent-ui-react/blob/master/LICENSE.md)
- Fluent UI React - Icons under [MIT License](https://github.com/Fmstrat/fluent-ui-react/blob/master/LICENSE.md) - Fluent UI - Icons under [MIT License](https://github.com/Fmstrat/fluentui/blob/master/LICENSE) with [restricted use](https://static2.sharepointonline.com/files/fabric/assets/microsoft_fabric_assets_license_agreement_nov_2019.pdf)
- Fluent UI - Icons under [MIT License](https://github.com/Fmstrat/fluentui/blob/master/LICENSE) with [restricted use](https://static2.sharepointonline.com/files/fabric/assets/microsoft_fabric_assets_license_agreement_nov_2019.pdf) - PKief's VSCode Material Icon Theme - Icons under [MIT License](https://github.com/Fmstrat/vscode-material-icon-theme/blob/master/LICENSE.md)
- PKief's VSCode Material Icon Theme - Icons under [MIT License](https://github.com/Fmstrat/vscode-material-icon-theme/blob/master/LICENSE.md) - DiemenDesign's LibreICONS - Icons under [MIT License](https://github.com/Fmstrat/LibreICONS/blob/master/LICENSE)
- DiemenDesign's LibreICONS - Icons under [MIT License](https://github.com/Fmstrat/LibreICONS/blob/master/LICENSE)

BIN
demo/installer.gif
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 259 KiB

After

Width:  |  Height:  |  Size: 4.4 MiB

15
icons/windows.svg
View File

@ -1,3 +1,14 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 2048 2048"> <svg version="1.2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 2048 2048" width="2048" height="2048">
<path d="M0 268l768-107v735H0V268zM1920 0v896H896V143L1920 0zM896 1024h1024v896L896 1777v-753zm-896 0h768v735L0 1652v-628z" fill="#73A1FB"/> <title>POO</title>
<defs>
<linearGradient id="g1" x2="1" gradientUnits="userSpaceOnUse" gradientTransform="matrix(-2048,-2048,2048,-2048,2048,2048)">
<stop offset="0" stop-color="#067cd6"/>
<stop offset=".4" stop-color="#0f85da"/>
<stop offset="1" stop-color="#7adcff"/>
</linearGradient>
</defs>
<style>
.s0 { fill: url(#g1) }
</style>
<path id="Windows" fill-rule="evenodd" class="s0" d="m228 0h746v974h-974v-746c0-125.9 102.1-228 228-228zm746 2048h-746c-125.9 0-228-102.1-228-228v-746h974zm846-2048c125.9 0 228 102.1 228 228v746h-974v-974zm228 1820c0 125.9-102.1 228-228 228h-746v-974h974z"/>
</svg> </svg>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 217 B

After

Width:  |  Height:  |  Size: 730 B