mirror of
https://github.com/winapps-org/winapps.git
synced 2025-06-23 06:33:02 +02:00
Updated README.md
This commit is contained in:
Rohan Barar
parent
a3ed167291
commit
75c790fd0d
285
README.md
285
README.md
@ -1,114 +1,116 @@
|
||||
# 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,
|
||||
including Nautilus integration for right-clicking on files of specific mime types to open them.
|
||||
<img src="demo/demo.gif" width=1000 alt="WinApps Demonstration Animation.">
|
||||
|
||||
<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
|
||||
- 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
|
||||
Universal application support is achieved by:
|
||||
1. Scanning Windows for any officially supported applications (list below).
|
||||
2. Scanning Windows for any other `.exe` files listed within the Windows Registry.
|
||||
|
||||
## 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:
|
||||
|
||||
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.
|
||||
*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.*
|
||||
|
||||
### Officially Supported Applications
|
||||
<table cellpadding="10" cellspacing="0" border="0">
|
||||
<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-reader-dc/icon.svg" width="100"></td><td>Adobe Acrobat Reader<br>(DC)</td>
|
||||
</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>
|
||||
</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>
|
||||
</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>
|
||||
</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>
|
||||
</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>
|
||||
</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>
|
||||
</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>
|
||||
</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>
|
||||
</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>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><img src="icons/windows.svg" width="100"></td><td>Windows<br>(Full RDP session)</td>
|
||||
<td> </td><td> </td>
|
||||
</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/aftereffects-cc/icon.svg" width="100"></td><td>Adobe After Effects<br>(CC)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
</table>
|
||||
|
||||
## 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.
|
||||
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:
|
||||
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.
|
||||
|
||||
- [Creating a virtual machine with Docker](docs/docker.md)
|
||||
- [Creating a virtual machine in KVM (outdated)](docs/KVM.md)
|
||||
### Step 2: Clone WinApps Repository and Dependencies
|
||||
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
|
||||
|
||||
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:
|
||||
> 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).
|
||||
|
||||
### Step 3: Create a WinApps Configuration File
|
||||
Create a configuration file at `~/.config/winapps/winapps.conf` containing the following:
|
||||
```bash
|
||||
RDP_USER="MyWindowsUser"
|
||||
RDP_PASS="MyWindowsPassword"
|
||||
@ -121,95 +123,52 @@ 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 can't be a user/PIN combination as those aren't valid for RDP access.
|
||||
`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.
|
||||
|
||||
Options:
|
||||
|
||||
- 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
|
||||
#### 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.
|
||||
- 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.
|
||||
- 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].
|
||||
- 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.
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
### 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:
|
||||
- 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
|
||||
Run the WinApps installer.
|
||||
```bash
|
||||
./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>
|
||||
|
||||
## 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:
|
||||
|
||||
- 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.
|
||||
## 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.
|
||||
|
||||
```bash
|
||||
./bin/winapps manual "C:\my\directory\executableNotInPath.exe"
|
||||
./bin/winapps manual executableInPath.exe
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
```bash
|
||||
./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
|
||||
```
|
||||
## Updating WinApps
|
||||
The installer can be run multiple times. To update your installation of WinApps:
|
||||
1. Run the WinApps installer to remove WinApps from your system.
|
||||
2. Pull the latest changes from the WinApps GitHub repository.
|
||||
3. Re-install WinApps using the WinApps installer.
|
||||
|
||||
## Shout-outs
|
||||
|
||||
- Some icons pulled from
|
||||
- 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)
|
||||
- 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)
|
||||
- Some icons used for the officially supported applications were sourced from:
|
||||
- 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)
|
||||
- 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)
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 259 KiB After Width: | Height: | Size: 4.4 MiB |
@ -1,3 +1,14 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 2048 2048">
|
||||
<path d="M0 268l768-107v735H0V268zM1920 0v896H896V143L1920 0zM896 1024h1024v896L896 1777v-753zm-896 0h768v735L0 1652v-628z" fill="#73A1FB"/>
|
||||
<svg version="1.2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 2048 2048" width="2048" height="2048">
|
||||
<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>
|
||||
|
Before Width: | Height: | Size: 217 B After Width: | Height: | Size: 730 B |
Loading…
x
Reference in New Issue
Block a user