diff --git a/README.md b/README.md index 6a12873..c67b031 100644 --- a/README.md +++ b/README.md @@ -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. \ No newline at end of file