GUI Web Base

   
   

A Docker base image to simplify the creation of downstream containers that run Linux GUI apps in a web browser.

⚡ Features

• Linux apps in your browser
• Non-root runtime - Uses a non-root user at runtime by default.
• Integrated clipboard - Seamless copy-paste between app and browser.
• Audio forwarding - Stream audio from the app to your browser seamlessly.
• Automatic restart - Apps relaunch automatically when closed.
• HTTPS redirect – Enforces secure connections over HTTPS, by default.
• Launch apps from UI – .desktop entries are exposed and can be launched via the UI.

✨ Getting Started

This image is designed to be used as a base for Dockerfiles.
Install a desired GUI app and call the following to launch it.

CMD ["start-app","[--no-restart]", "<app>", "[args...]"]

• Example Dockerfile with xterm

# Prefer version pinning (at least a major, e.g. :v1)
# Pinning to <major>.<minor> (e.g. :v1.1) limits updates to patches only.
FROM aandree5/gui-web-base:v1.1

# Install app
RUN apt-get update && \
    apt-get install -y xterm && \
    && apt-get autoremove \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Start app
CMD ["start-app", "xterm"]

• Build and run

# Build the image
docker build -t gui-web-xterm .

# Run it
docker run -d -p 443:5443 gui-web-xterm

To access the app open https://localhost in the browser.

⚙️ Configuration

• Build-Time Arguments

These can be set using --build-arg during docker build to define default values baked into the image.

Argument	Description	Default	Example
PUID	Default UID for the build/runtime user.	1000	--build-arg PUID=1000
PGID	Default GID for the build/runtime group.	1000	--build-arg PGID=1000
GWB_HOME	Default home directory for the runtime user.	/home/gwb	--build-arg GWB_HOME=/myapp
UMASK	Default file creation mask applied at runtime.	077	--build-arg UMASK=027

• Runtime Environment Variables

These can be overridden by any downstream image or container using ENV or -e flags.

Variable	Description	Default	Example
PUID	Runtime user ID. Used to remap file ownership and process permissions.	1000	ENV PUID=1000 or -e PUID=1000
PGID	Runtime group ID. Used to remap file ownership and process permissions.	1000	ENV PGID=1000 or -e PGID=1000
APP_DIRS	Space-separated list of directories to create and assign to the runtime user.	(unset)	ENV APP_DIRS="/myapp/config /var/cache" or -e APP_DIRS="..."
GWB_HOME	Runtime user’s home directory. Overrides the build-time default.	/home/gwb	ENV GWB_HOME=/myapp or -e GWB_HOME=/myapp
UMASK	File creation mask used during startup. Controls default permissions for generated files.	077	ENV UMASK=027 or -e UMASK=027
ALLOW_HTTP	Enables or disables automatic HTTP-to-HTTPS redirection.	false	ENV ALLOW_HTTP=true or -e FORCE_HTTPS_REDIRECT=true

ALLOW_HTTP is recomended set to false to keep all traffic secure, even with self-signed certificates. In some cases it can be usefull to allow HTTP access, shuch as if the app is going to be behind a reverse proxy, which is handling SSL certificates.

• App Launch Flags

These options can be passed to CMD in your Dockerfile to customize app behavior.

Option	Description	Default	Example
--no-restart	Prevents the app from restarting when its window is closed.	(enabled)	CMD ["start-app", "--no-restart", "my-app"]
--title	Sets the browser tab title for the web interface.	GUI Web Base	CMD ["start-app", "--title", "My Web App", "my-app"]
--min-quality *	Sets the minimum image encoding quality (1–100). Lower values save bandwidth.	0 (auto)	CMD ["start-app", "--min-quality", "80", "my-app"]
--min-speed *	Sets the minimum encoding speed (1–100). Higher values reduce latency.	0 (auto)	CMD ["start-app", "--min-speed", "50", "my-app"]
--auto-refresh-delay *	Delay (in seconds) before sending a lossless refresh after lossy updates.	0.25	CMD ["start-app", "--auto-refresh-delay", "0.2", "my-app"]

* See the Xpra manual for more information.

• Xpra Content-Type Mapping

Use the configure-xpra script during build to append content-type rules to Xpra’s config files. Pass mappings using --content-type in the format [fallback:]<type>:<key>=<value>.

# Multiple flags can be passed
# If the value contains spaces or special characters, wrap the value in quotes.
RUN configure-xpra \
  --content-type role:gimp-dock=text \
  --content-type "title:- Gmail -=text" \
  --content-type class-instance:xterm=text \
  --content-type commands:my_special_command=picture \
  --content-type fallback:role:browser=browser

• Supported Match Types

Type	Format Example	Description
role	role:gimp-dock=text	Matches the window's internal role name (e.g. toolbars, docks, dialogs).
title	title:- Gmail -=text	Matches the window title shown in the title bar.
class-instance	class-instance:xterm=text	Matches the X11 class/instance name of the window.
commands	command:my_special_command=picture	Matches the command used to launch the application.
fallback	fallback:role:browser=browser (generic fallback)	Applies when no other match succeeds and is evaluated last as a catch-all rule.

For more details, see the Xpra tuning documentation.

🎛️ Menu Integration

This image includes a built-in freedesktop-compliant menu file that allows installed apps with .desktop files to be discovered and launched from the UI.

If an app provides a .desktop entry (installed either to /usr/share/applications or ~/.local/share/applications), it will automatically appear in the browser-based menu, no extra configuration needed.

🏷️ Versioning & Tags

This project follows Semantic Versioning and uses automated releases.

Tag Overview

Format	Example	Description
latest	-	Always the newest, may include breaking changes.
v<major>	v1	Latest stable for a major version. No breaking changes.
v<major>.<minor>	v1.1	Latest patch for a minor version. No new featues.
v<major>.<minor>.<patch>	v1.1.0	Fixed version, only changes if manually updated.

🛠️ Contributing

Contributions are welcome! Please follow these steps to get set up:

1. Clone the repository:

   git clone https://github.com/Aandree5/gui-web-base.git
   cd gui-web-base

2. Install pre-commit hooks (for license headers, linting, etc.):

   pip install pre-commit
   pre-commit install

3. Follow Conventional Commits for commit messages:

   • feat: - New feature
   • fix: - Bug fix
   • docs: - Documentation changes
   • chore: - Maintenance or tooling
   • ci: - CI/CD or workflow updates
   • refactor: - Code improvements without changing behavior
   • revert: - Revert a previous commit

4. Open a Pull Request against main.

📦 Tech Stack Overview

• Debian trixie-slim
  Stable Linux base, optimized for performance and size.

• Xpra
  Enables remote access to Linux desktop apps via the web.

• Xpra HTML5 Client
  For interacting with GUI apps through Xpra.

📚 Resources

• Code of Conduct
• Contributing Guide
• Apache 2.0 License
• Security Policy

☕ Support

If you find the project useful, consider supporting its development! Your donations help cover costs and fund future improvements.

You can support through: