Skip to content

docs: document base image selection decision #51

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mark-e-deyoung merged 2 commits into from
May 1, 2026
Merged

docs: document base image selection decision #51

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5e9795f
docs: document base image selection decision
google-labs-jules[bot] May 1, 2026
b689d9a
test: bump playwright e2e image to v1.59.0
google-labs-jules[bot] May 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,21 @@

WineBot runs Windows GUI applications inside a Linux container using Wine, Xvfb, and a lightweight window manager. It exposes an HTTP API for programmatic control.

## Base Image Selection

Choosing the correct base image is critical for supporting modern versions of Wine while maintaining container best practices. The following options were evaluated:

* **Ubuntu LTS + WineHQ Repository:** While this provides access to the latest Wine versions, Ubuntu images are larger, and relying on third-party repositories introduces build-time failure risks (e.g., repository downtime or GPG key changes).
* **Alpine Linux:** Offers the smallest possible footprint. However, Alpine uses `musl` libc instead of `glibc`. Wine heavily relies on `glibc`, making Alpine highly incompatible and requiring complex, fragile workarounds.
* **Arch Linux:** Provides native, bleeding-edge packages without external repositories. However, rolling releases lack the stability required for predictable CI/CD pipelines and production container runtimes.
* **Debian Stable + WineHQ / Backports:** Provides a rock-solid base, but backports often lag behind the latest Wine releases, and using WineHQ reintroduces third-party dependency risks.

**Final Decision:** WineBot uses a **minimal Debian Trixie (Testing) base** (`debian:trixie-slim`) layered with specific requirements. This approach was chosen because it:
1. **Provides Modern Wine:** Access to recent Wine versions directly from native Debian repositories without third-party repos.
2. **Maintains Minimal Size:** The slim variant keeps the base layer small.
3. **Ensures High Compatibility:** Full `glibc` support ensures standard behavior for Wine and Windows applications.
4. **Is Future-Proof:** Using the upcoming stable release prepares the project for the future without major migrations.

## System Layers

1. **Application Layer (Windows)**
Expand Down
2 changes: 1 addition & 1 deletion tests/e2e/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
FROM mcr.microsoft.com/playwright/python:v1.58.0-noble
FROM mcr.microsoft.com/playwright/python:v1.59.0-noble

# Set up workspace first to copy requirements
WORKDIR /work
Expand Down
Loading