Update README.md
This commit is contained in:
@@ -1,82 +1,286 @@
|
|||||||
# Wine Desktop
|
# Wine Desktop
|
||||||
|
|
||||||
Wine Desktop extends the official Pterodactyl Wine yolk with a persistent virtual XFCE desktop. It is intended for Windows GUI applications that need a display, VNC access, or browser-based noVNC access inside a Pterodactyl or Pelican server.
|
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
|
## Features
|
||||||
|
|
||||||
- Based on `ghcr.io/ptero-eggs/yolks:wine_latest`.
|
- Based on the official `ghcr.io/ptero-eggs/yolks:wine_latest` image.
|
||||||
- XFCE on Xvfb with configurable resolution.
|
- Persistent virtual XFCE desktop.
|
||||||
- Direct VNC on TCP `5900` and browser VNC on TCP `6080`.
|
- Hardware-independent X11 desktop powered by Xvfb.
|
||||||
- Persistent Wine prefix at `/home/container/.wine`.
|
- Optional direct VNC access.
|
||||||
- PulseAudio, Mesa, fonts, winetricks, winbind, and common archive tools.
|
- Optional browser-based noVNC access.
|
||||||
- Retains the official yolk's Steam update, Gecko/Mono, winetricks, and startup handling.
|
- 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.
|
||||||
|
|
||||||
## Architecture
|
---
|
||||||
|
|
||||||
The image keeps the yolk's `/usr/bin/tini -g --` process and inherited command. Its entrypoint starts Xvfb, D-Bus, XFCE, x11vnc, noVNC, and the Wine prefix once, then executes the inherited `/bin/bash /entrypoint.sh`. The official entrypoint continues to expand `STARTUP`, perform optional updates and winetricks actions, and launch the application.
|
# How it works
|
||||||
|
|
||||||
The Wine prefix is not deleted or rebuilt when the container restarts. Store the server data in the normal Pterodactyl volume to keep it persistent.
|
When the container starts, Wine Desktop prepares a complete graphical Linux session before your application launches.
|
||||||
|
|
||||||
## Installation
|
The startup sequence is:
|
||||||
|
|
||||||
Build locally:
|
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
|
```bash
|
||||||
git clone https://git.lexian.dev/Lexian-droid/OpenClaw-pterodactyl-wine-gui-egg.git WineDesktop
|
git clone https://git.lexian.dev/Lexian-droid/OpenClaw-pterodactyl-wine-gui-egg.git WineDesktop
|
||||||
cd WineDesktop
|
cd WineDesktop
|
||||||
|
```
|
||||||
|
|
||||||
|
Build the image:
|
||||||
|
|
||||||
|
```bash
|
||||||
docker build -t wine-desktop:latest .
|
docker build -t wine-desktop:latest .
|
||||||
```
|
```
|
||||||
|
|
||||||
The image exposes `5900/tcp` and `6080/tcp`. Publish those ports if running Docker directly:
|
If running directly with Docker:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
docker run --rm -it -p 5900:5900 -p 6080:6080 \
|
docker run \
|
||||||
-e STARTUP='wine /home/container/application.exe' \
|
--rm \
|
||||||
|
-it \
|
||||||
|
-p 5900:5900 \
|
||||||
|
-p 6080:6080 \
|
||||||
|
-e STARTUP="wine /home/container/application.exe" \
|
||||||
wine-desktop:latest
|
wine-desktop:latest
|
||||||
```
|
```
|
||||||
|
|
||||||
For Pterodactyl or Pelican, import `egg-wine-desktop.json` into the nest, select the published image (or add your own registry tag), and create a server with the Wine Desktop Egg. Add allocations for ports 5900 and 6080 when your panel supports additional allocations.
|
For Pterodactyl or Pelican:
|
||||||
|
|
||||||
## Startup and variables
|
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.
|
||||||
|
|
||||||
The Egg's default startup is `wine {{SERVER_EXECUTABLE}}`, with `SERVER_EXECUTABLE` defaulting to `application.exe`. Set it to a path such as `MyApp/MyApp.exe` or use a custom startup command when needed. The underlying yolk continues to receive and evaluate its normal `STARTUP` value.
|
---
|
||||||
|
|
||||||
Useful variables:
|
# Configuration
|
||||||
|
|
||||||
| Variable | Default | Purpose |
|
## Startup
|
||||||
| --- | --- | --- |
|
|
||||||
| `SERVER_EXECUTABLE` | `application.exe` | Executable used by the Egg startup command |
|
|
||||||
| `DISPLAY_WIDTH` | `1280` | Virtual screen width |
|
|
||||||
| `DISPLAY_HEIGHT` | `720` | Virtual screen height |
|
|
||||||
| `WINEPREFIX` | `/home/container/.wine` | Persistent Wine prefix |
|
|
||||||
| `VNC_PASSWORD` | empty | Optional direct VNC password, up to 8 characters |
|
|
||||||
| `VNC_PORT` | `5900` | x11vnc port |
|
|
||||||
| `NOVNC_PORT` | `6080` | noVNC/websockify port |
|
|
||||||
|
|
||||||
## Connecting
|
The default startup command is:
|
||||||
|
|
||||||
Direct VNC clients connect to the server allocation on port `5900`. If `VNC_PASSWORD` is blank, VNC authentication is disabled; protect the allocation with your firewall or proxy.
|
```text
|
||||||
|
wine {{SERVER_EXECUTABLE}}
|
||||||
|
```
|
||||||
|
|
||||||
Browser clients open `http://SERVER:6080/vnc.html` and connect to the displayed VNC endpoint. Use HTTPS or a reverse proxy when exposing noVNC beyond a trusted network.
|
By default:
|
||||||
|
|
||||||
## Troubleshooting
|
```text
|
||||||
|
SERVER_EXECUTABLE=application.exe
|
||||||
|
```
|
||||||
|
|
||||||
- **Black screen:** confirm ports are allocated and inspect `/tmp/wine-desktop-xfce.log` and `/tmp/wine-desktop-x11vnc.log` in the container.
|
You can change this to any executable inside `/home/container`.
|
||||||
- **Application does not start:** run the exact command interactively and check that the executable exists under `/home/container`; the official yolk's `STARTUP` is evaluated by Bash.
|
|
||||||
- **Prefix problems:** stop the server before changing Wine architecture or winetricks settings. Back up `.wine` before manually repairing it.
|
|
||||||
- **noVNC loads but cannot connect:** ensure both 6080 and 5900 are reachable from the container network; websockify forwards 6080 to localhost:5900.
|
|
||||||
- **No audio:** applications must support PulseAudio. The image includes the client and server packages, but application-specific audio configuration may still be required.
|
|
||||||
|
|
||||||
## FAQ
|
Examples:
|
||||||
|
|
||||||
**Does this replace the official Wine yolk?** No. It uses it as the base and invokes its original entrypoint after the desktop is ready.
|
```text
|
||||||
|
Launcher.exe
|
||||||
|
```
|
||||||
|
|
||||||
**Does it support Steam server updates and winetricks?** Yes. The inherited entrypoint remains responsible for those features.
|
```text
|
||||||
|
Game/Server.exe
|
||||||
|
```
|
||||||
|
|
||||||
**Is the desktop secure by default?** VNC is bound for container access and is intended to be protected by Pterodactyl allocations, firewall rules, or a reverse proxy. Set `VNC_PASSWORD` for direct VNC authentication and do not expose unprotected ports publicly.
|
```text
|
||||||
|
Tools/Editor.exe
|
||||||
|
```
|
||||||
|
|
||||||
**Can I use this with Pelican?** Yes. The Egg uses the modern `PTDL_v2` format and standard Docker image/startup fields.
|
---
|
||||||
|
|
||||||
## License
|
## Environment Variables
|
||||||
|
|
||||||
This project is licensed under the MIT License. The base Wine yolk and its components retain their own licenses.
|
| 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.
|
||||||
Reference in New Issue
Block a user