286 lines
6.2 KiB
Markdown
286 lines
6.2 KiB
Markdown
# Wine Desktop
|
|
|
|
Wine Desktop is a Docker image and Pterodactyl/Pelican Egg that enables Windows desktop applications to run inside a fully featured Linux desktop environment powered by Wine.
|
|
|
|
Unlike the official Wine yolk, which is primarily intended for command-line or dedicated server applications, Wine Desktop provides a persistent virtual XFCE desktop running on Xvfb, allowing graphical Windows software to run as if it were on a normal desktop system. Applications can be accessed remotely through a traditional VNC client or directly from a web browser using noVNC.
|
|
|
|
The project was originally developed while bringing OpenClaw to Pterodactyl, but it is completely application-agnostic. It can be used for virtually any Windows program that runs under Wine, including launchers, editors, utilities, game tools, and other GUI applications.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- Based on the official `ghcr.io/ptero-eggs/yolks:wine_latest` image.
|
|
- Persistent virtual XFCE desktop.
|
|
- Hardware-independent X11 desktop powered by Xvfb.
|
|
- Optional direct VNC access.
|
|
- Optional browser-based noVNC access.
|
|
- Persistent Wine prefix stored inside the server volume.
|
|
- Built-in PulseAudio support.
|
|
- Mesa OpenGL libraries for hardware-independent rendering.
|
|
- Includes Winetricks, Gecko, Mono, Winbind, common fonts, and archive utilities.
|
|
- Preserves the official Wine yolk's startup behavior, SteamCMD support, Winetricks integration, and automatic dependency handling.
|
|
|
|
---
|
|
|
|
# How it works
|
|
|
|
When the container starts, Wine Desktop prepares a complete graphical Linux session before your application launches.
|
|
|
|
The startup sequence is:
|
|
|
|
1. Start an Xvfb virtual display.
|
|
2. Create a D-Bus session.
|
|
3. Launch PulseAudio (if available).
|
|
4. Start an XFCE desktop environment.
|
|
5. Optionally start x11vnc.
|
|
6. Optionally start noVNC/websockify.
|
|
7. Initialize the Wine prefix (first launch only).
|
|
8. Hand execution back to the official Wine yolk.
|
|
9. Launch your Windows application using the Egg startup command.
|
|
|
|
Because the original Pterodactyl Wine entrypoint is still used, all existing functionality—including Steam updates, Winetricks installation, Gecko/Mono installation, and startup handling—continues to work exactly as expected.
|
|
|
|
---
|
|
|
|
# Why this exists
|
|
|
|
Many Windows applications require a graphical desktop even if they are ultimately managed through Pterodactyl.
|
|
|
|
Examples include:
|
|
|
|
- Game launchers
|
|
- Dedicated server tools
|
|
- Level editors
|
|
- Configuration utilities
|
|
- Asset management software
|
|
- Legacy Windows applications
|
|
- Programs that require an interactive desktop
|
|
|
|
Wine Desktop makes these applications feel much closer to running on a normal Windows machine while still benefiting from containerization and Pterodactyl's management features.
|
|
|
|
---
|
|
|
|
# Installation
|
|
|
|
Clone the repository:
|
|
|
|
```bash
|
|
git clone https://git.lexian.dev/Lexian-droid/OpenClaw-pterodactyl-wine-gui-egg.git WineDesktop
|
|
cd WineDesktop
|
|
```
|
|
|
|
Build the image:
|
|
|
|
```bash
|
|
docker build -t wine-desktop:latest .
|
|
```
|
|
|
|
If running directly with Docker:
|
|
|
|
```bash
|
|
docker run \
|
|
--rm \
|
|
-it \
|
|
-p 5900:5900 \
|
|
-p 6080:6080 \
|
|
-e STARTUP="wine /home/container/application.exe" \
|
|
wine-desktop:latest
|
|
```
|
|
|
|
For Pterodactyl or Pelican:
|
|
|
|
1. Import `egg-wine-desktop.json`.
|
|
2. Select the Wine Desktop Docker image.
|
|
3. Create a server.
|
|
4. Allocate ports for VNC and/or noVNC if desired.
|
|
5. Upload your Windows application.
|
|
6. Start the server.
|
|
|
|
---
|
|
|
|
# Configuration
|
|
|
|
## Startup
|
|
|
|
The default startup command is:
|
|
|
|
```text
|
|
wine {{SERVER_EXECUTABLE}}
|
|
```
|
|
|
|
By default:
|
|
|
|
```text
|
|
SERVER_EXECUTABLE=application.exe
|
|
```
|
|
|
|
You can change this to any executable inside `/home/container`.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
Launcher.exe
|
|
```
|
|
|
|
```text
|
|
Game/Server.exe
|
|
```
|
|
|
|
```text
|
|
Tools/Editor.exe
|
|
```
|
|
|
|
---
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|-----------|---------|-------------|
|
|
| SERVER_EXECUTABLE | application.exe | Windows executable to launch |
|
|
| DISPLAY_WIDTH | 1280 | Desktop width |
|
|
| DISPLAY_HEIGHT | 720 | Desktop height |
|
|
| DISPLAY_DEPTH | 24 | Color depth |
|
|
| WINEPREFIX | /home/container/.wine | Persistent Wine installation |
|
|
| ENABLE_VNC | true | Enable x11vnc |
|
|
| ENABLE_NOVNC | true | Enable browser-based noVNC |
|
|
| VNC_PORT | 5900 | x11vnc listening port |
|
|
| NOVNC_PORT | 6080 | noVNC listening port |
|
|
| VNC_PASSWORD | *(blank)* | Optional VNC password |
|
|
| WINEDEBUG | -all | Wine debug output |
|
|
| WINEDLLOVERRIDES | *(blank)* | DLL overrides |
|
|
| LANG | en_US.UTF-8 | Locale |
|
|
| TZ | UTC | Container timezone |
|
|
|
|
---
|
|
|
|
# Connecting
|
|
|
|
## VNC
|
|
|
|
Connect using any VNC client to:
|
|
|
|
```
|
|
SERVER_IP:5900
|
|
```
|
|
|
|
If a password is configured, enter the value of `VNC_PASSWORD`.
|
|
|
|
---
|
|
|
|
## noVNC
|
|
|
|
Open your browser:
|
|
|
|
```
|
|
http://SERVER_IP:6080/vnc.html
|
|
```
|
|
|
|
The browser interface connects to the running desktop without requiring a standalone VNC client.
|
|
|
|
---
|
|
|
|
# Troubleshooting
|
|
|
|
### Black screen
|
|
|
|
Check:
|
|
|
|
- `/tmp/wine-desktop-xfce.log`
|
|
- `/tmp/wine-desktop-x11vnc.log`
|
|
|
|
---
|
|
|
|
### Application will not start
|
|
|
|
Verify:
|
|
|
|
- The executable exists.
|
|
- `SERVER_EXECUTABLE` points to the correct file.
|
|
- The application is compatible with Wine.
|
|
|
|
---
|
|
|
|
### Wine prefix issues
|
|
|
|
The Wine prefix is persistent.
|
|
|
|
If it becomes corrupted:
|
|
|
|
1. Stop the server.
|
|
2. Back up `.wine`.
|
|
3. Delete or repair the prefix.
|
|
4. Restart the server.
|
|
|
|
---
|
|
|
|
### noVNC won't connect
|
|
|
|
Verify:
|
|
|
|
- VNC is enabled.
|
|
- noVNC is enabled.
|
|
- Port 5900 is reachable internally.
|
|
- Port 6080 is allocated externally.
|
|
|
|
---
|
|
|
|
# FAQ
|
|
|
|
### Is this a replacement for the official Wine yolk?
|
|
|
|
No.
|
|
|
|
Wine Desktop extends the official Wine yolk while preserving its startup behavior and update mechanisms.
|
|
|
|
---
|
|
|
|
### Does this only work with OpenClaw?
|
|
|
|
No.
|
|
|
|
OpenClaw was simply the application used during development and testing.
|
|
|
|
Wine Desktop is designed to run **any Windows GUI application that works under Wine**.
|
|
|
|
---
|
|
|
|
### Can I disable VNC?
|
|
|
|
Yes.
|
|
|
|
Set:
|
|
|
|
```
|
|
ENABLE_VNC=false
|
|
```
|
|
|
|
---
|
|
|
|
### Can I disable noVNC?
|
|
|
|
Yes.
|
|
|
|
Set:
|
|
|
|
```
|
|
ENABLE_NOVNC=false
|
|
```
|
|
|
|
When VNC is disabled, noVNC is automatically disabled as well.
|
|
|
|
---
|
|
|
|
### Is the Wine prefix persistent?
|
|
|
|
Yes.
|
|
|
|
The Wine prefix is stored inside your server's data volume and survives restarts and container rebuilds.
|
|
|
|
---
|
|
|
|
# License
|
|
|
|
This project is licensed under the MIT License.
|
|
|
|
Wine Desktop builds upon the official Pterodactyl Wine yolk. All third-party software included in the image remains subject to its respective licenses. |