Update README.md
This commit is contained in:
@@ -1,82 +1,286 @@
|
||||
# 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
|
||||
|
||||
- Based on `ghcr.io/ptero-eggs/yolks:wine_latest`.
|
||||
- XFCE on Xvfb with configurable resolution.
|
||||
- Direct VNC on TCP `5900` and browser VNC on TCP `6080`.
|
||||
- Persistent Wine prefix at `/home/container/.wine`.
|
||||
- PulseAudio, Mesa, fonts, winetricks, winbind, and common archive tools.
|
||||
- Retains the official yolk's Steam update, Gecko/Mono, winetricks, and startup handling.
|
||||
- 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.
|
||||
|
||||
## 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
|
||||
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 .
|
||||
```
|
||||
|
||||
The image exposes `5900/tcp` and `6080/tcp`. Publish those ports if running Docker directly:
|
||||
If running directly with Docker:
|
||||
|
||||
```bash
|
||||
docker run --rm -it -p 5900:5900 -p 6080:6080 \
|
||||
-e STARTUP='wine /home/container/application.exe' \
|
||||
docker run \
|
||||
--rm \
|
||||
-it \
|
||||
-p 5900:5900 \
|
||||
-p 6080:6080 \
|
||||
-e STARTUP="wine /home/container/application.exe" \
|
||||
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 |
|
||||
| --- | --- | --- |
|
||||
| `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 |
|
||||
## Startup
|
||||
|
||||
## 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.
|
||||
- **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.
|
||||
You can change this to any executable inside `/home/container`.
|
||||
|
||||
## 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