{"id":13510540,"url":"https://github.com/ken-okabe/wayland-desktop-container","last_synced_at":"2025-07-29T12:31:05.948Z","repository":{"id":45768035,"uuid":"85324864","full_name":"ken-okabe/wayland-desktop-container","owner":"ken-okabe","description":"How to set up your nested Wayland Desktop Environment with systemd-nspawn container, like VirtualBox","archived":false,"fork":false,"pushed_at":"2019-06-06T09:34:42.000Z","size":9,"stargazers_count":77,"open_issues_count":2,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-01T11:34:21.684Z","etag":null,"topics":["backup","containers","desktop-environment","hardware","kwin","shell","shell-script","systemd-container","systemd-nspawn","virtualization","wayland","xfce","xorg"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ken-okabe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-17T15:08:42.000Z","updated_at":"2024-10-29T19:00:24.000Z","dependencies_parsed_at":"2022-08-30T23:21:33.187Z","dependency_job_id":null,"html_url":"https://github.com/ken-okabe/wayland-desktop-container","commit_stats":null,"previous_names":["ken-okabe/wayland-desktop-container"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ken-okabe%2Fwayland-desktop-container","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ken-okabe%2Fwayland-desktop-container/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ken-okabe%2Fwayland-desktop-container/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ken-okabe%2Fwayland-desktop-container/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ken-okabe","download_url":"https://codeload.github.com/ken-okabe/wayland-desktop-container/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228012215,"owners_count":17855984,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backup","containers","desktop-environment","hardware","kwin","shell","shell-script","systemd-container","systemd-nspawn","virtualization","wayland","xfce","xorg"],"created_at":"2024-08-01T02:01:43.087Z","updated_at":"2024-12-03T23:11:21.863Z","avatar_url":"https://github.com/ken-okabe.png","language":null,"funding_links":[],"categories":["Others","shell"],"sub_categories":[],"readme":"# How to set up your nested Wayland Desktop Environment with systemd-nspawn container, like VirtualBox\n\n\nThis tutorial walks you through setting up [Wayland](https://wiki.archlinux.org/index.php/wayland) Desktop Environment with linux [systemd-nspawn](https://wiki.archlinux.org/index.php/Systemd-nspawn) container on your computer. This is similar to VMware Workstation or VirtualBox, but linux only with minimal overhead performance.\n\n## A Quick Look at the final result\n\n![](https://raw.githubusercontent.com/wiki/kenokabe/wayland-desktop-container/images/Screenshot_20170318_025052.png)\n\n## Features and benefits\n\n✓ Hardware independent containerOS by the hardware abstraction with extremely efficient, minimal performance overhead method by systemd-nspawn container technology  \n✓ 100% portable among systemd enabled linux hosts, easy backup and recovery  \n✓ Direct rendering works such as 3D Desktop effects  \n✓ Video and Sound works  \n✓ Network works out of the box  \n✓ Less likely to mess up the hostOS and infrequent reboot operations for the hostOS and the hardware, instead, enjoy the instant virtual boot, poweroff and reboot of the containerOS.\n\n## Summary of How to\n\n1. Launch `kwin_wayland` window,  \nthat is nested on your current desktop environment.\n\n2. Boot your container OS with `systemd-nspawn`\n\n3. From the containerOS console:  \n(a) Launch a Desktop Environment such as [XFCE](https://wiki.archlinux.org/index.php/xfce) or [LXQt](https://wiki.archlinux.org/index.php/LXQt) to the targeted `kwin_wayland` window.  \n(b) Simply prepare your favorite launcher app like [synapse](https://launchpad.net/synapse-project) or [xfce4-panel](http://packages.ubuntu.com/xenial/xfce4-panel) alone for a minimal setup.\n\n# Walk through\n\n## HostOS with minimal applications\n\n![](https://raw.githubusercontent.com/wiki/kenokabe/wayland-desktop-container/images/Screenshot_20170318_020953.png)\n\nThe hostOS can be any linuxOS with systemd and the desktop environment can be either Wayland or legacy X11.\n\nAlghough, Wayland hostOS is obviously preferable, the situation is still immature. As of March 2017, only Fedora 25 sports Wayland-based GNOME session as the default over the X11-based one, but the other distros does not. The latest version of KDE-Plasma is stable with X11/Xorg, but unstable with Wayland.\n\nProbably, if you use GNOME for the host environment, go for Wayland, but if Plasma or other DE, be conservative to use X11/Xorg for stability.\n\nThis method works very well on both conditions, and personally, I use [Arch Linux](https://wiki.archlinux.org/index.php/Arch_Linux) with [KDE-Plasma(X11/Xorg)](https://wiki.archlinux.org/index.php/KDE).\n\n## Install `systemd-nspawn` and `kwin_wayland`\n\nSome distro such as Arch already has `systemd-nspawn`, but others such as Ubuntu does not.\n\n#### systemd-nspawn\n[Binary package “systemd-container” in ubuntu xenial](https://launchpad.net/ubuntu/xenial/+package/systemd-container)\n\n#### kwin-wayland\n[Binary package “kwin-wayland” in ubuntu xenial](https://launchpad.net/ubuntu/xenial/+package/kwin-wayland)\n\nArch probably has `kwin_wayland` in `xorg-server-xwayland` package.\n\n## Launch kwin_wayland window\n\n![](https://raw.githubusercontent.com/wiki/kenokabe/wayland-desktop-container/images/Screenshot_20170318_021150.png)\n\n`KWin` is known as one of the most feature complete and most stable window managers.\nThis is a direct rendering enabled `wayland` window space managed by `KWin`, and nested on your current desktop environment.\n\n\u003e [Starting a nested KWin](https://community.kde.org/KWin/Wayland#Starting_a_nested_KWin) @KWin/Wayland -  KDE Community Wiki  \nSince 5.3 it is possible to start a nested KWin instance under either X11 or Wayland:\n\n```bash\nexport $(dbus-launch); \\\nkwin_wayland --xwayland \u0026;\n```\n\n`export (dbus-launch);` for `fish` shell\n\n\n\n## Boot your containerOS\n\n![](https://raw.githubusercontent.com/wiki/kenokabe/wayland-desktop-container/images/Screenshot_20170318_064041.png)\n\n```\nsudo systemd-nspawn \\\n-bD /YOUR_MACHINE_ROOT_DIRECTORY \\\n--volatile=no \\\n--bind-ro=/home/YOUR_USERNAME/.Xauthority \\\n--bind=/run/user/1000 \\\n--bind=/tmp/.X11-unix \\\n--bind=/dev/shm \\\n--bind=/dev/dri \\\n--bind=/run/dbus/system_bus_socket \\\n--bind=/YOUR_DATA_DIRECTORY\n```\n\nBind `/YOUR_DATA_DIRECTORY` of the hostOS to the containerOS, so that you can share the data directory between both, at the same time, your containerOS can stay as small and clean as possible and good for portability and backup/restore.\n\nLogin the containerOS console.\n\n##### Typically, you build your container distro OS from minimal/server OS images.\n\nRemember, **you do not need to instal X11/Xorg display server, or wayland for containerOS** since `kwin_wayland` window plays the role.\n\n## Launch a DesktopEnvironment (XFCE)  to the targeted `kwin_wayland` window.  \n\n![](https://raw.githubusercontent.com/wiki/kenokabe/wayland-desktop-container/images/Screenshot_20170318_064335.png)\n\nRemember, KWin is already running, and it's a feature complete and powerful WindowManager. You can launch and switch tasks with KWin via shortcut-keys, or prepare your favorite launcher app like `synapse` or `xfce4-panel` for a minimal setup.\n\nHowever, if we need more user friendly Desktop Environments, just install and launch `XFCE` or `LXQt` that can run along with `KWin`.\n\nFrom the containerOS console:\n\n```bash\nexport XAUTHORITY=/home/YOUR_USERNAME/.Xauthority; \\\nexport XDG_RUNTIME_DIR=/run/user/1000; \\\nexport CLUTTER_BACKEND=x11; \\\nexport QT_X11_NO_MITSHM=1; \\\nxfce4-session --display :1;\n```\n\n![](https://raw.githubusercontent.com/wiki/kenokabe/wayland-desktop-container/images/Screenshot_20170318_064448.png)\n\n\n## Maximize and remove the frame of the kwin_wayland window as default\n\n![](https://raw.githubusercontent.com/wiki/kenokabe/wayland-desktop-container/images/Screenshot_20170318_022127.png)\n![](https://raw.githubusercontent.com/wiki/kenokabe/wayland-desktop-container/images/Screenshot_20170318_022156.png)\n\nProbably, you want to remove the frame of the containerOS, this is how to on Plasma (DE of the HostOS).\n\n\n## Final result\n\n![](https://raw.githubusercontent.com/wiki/kenokabe/wayland-desktop-container/images/Screenshot_20170318_025052.png)\n![](https://raw.githubusercontent.com/wiki/kenokabe/wayland-desktop-container/images/Screenshot_20170318_090100.png)\n\nConfirm XFCE environment recognizes that running on XWAYLAND display.\n\n[XWayland](https://wiki.archlinux.org/index.php/Wayland#XWayland) implements a compatibility layer to seamlessly run legacy X11 applications on Wayland.\n\nSo far, more like exceptionally, if you install [GUI libraries of wayland](https://wiki.archlinux.org/index.php/wayland#GUI_libraries), with a certain flag, you can see the GUI applications run natively on wayland.\n\n![](https://raw.githubusercontent.com/wiki/kenokabe/wayland-desktop-container/images/Screenshot_20170318_093932.png)\n\nThe left is `kate` window with Xorg/X11 compatiblity mode.  \nThe right is the window with wayland native mode.\n\nAs you can see the native wayland app does not reflect the current window theme and the XFCE panel does not show the app task, and you cannot tell the difference of the performance as long as you use the normal applications of PC.\n\nSo, probably there's not much reason to pursuit wayland native mode app.\nbut the situation can be different for 3D games, and significantly different on small devices such as Raspberry Pi.\n\n## (Optional) legacy X11/Xorg\n Althogh this tutorial focuses on wayland nested window, [Xephyr](https://wiki.archlinux.org/index.php/Xephyr) (a nested X server that runs as an X application) has been around for a long time.\n\nUnlike `kwin_wayland`, `Xepher` is not optimized for direct rendering and KWin Window manager is not bundled, so if you run KWin or other direct rendering composer on top of `Xepher`, things are going slow and inefficient, therefore, not recommended, but here's how:\n\n```bash\nXephyr -ac -screen 1200x700 -resizeable -reset :1 \u0026;\n```        \n\n## HostOS and ContainerOS interaction\n\nYou cannot Copy\u0026Paste between HostOS and ContainerOS.  \nYou may consider to use [GoogleKeep](https://play.google.com/store/apps/details?id=com.google.android.keep\u0026hl=en) to share contents between HostOS and ContainerOS, and of course, you shold have shared directories via systemd-nspawn bind.\n\n## Portability\n\nYou may \"backup/recover\" or \"copy\" or \"move\" the continerOS to anywhere regardless of\n\n- Kernel updates\n- Hardware drivers\n- Disk partitions (`/etc/fstab` etc.)\n- GRUB/UEFI configurations\n\nor any other typical integration glitches!\n\nJust be aware of the host kernel versions.\n\n## Backup\n\nyour machines directory `./machines`  \nyour machines backup directory `./machines-bak`  \nyour machine image directory `arch1`\n\n```bash\ncd ~/machines/\nsudo tar -cpf ~/machines-bak/arch1.tar arch1 --totals\n```\n\n## Recovery\n\n```bash\ncd ~/machines/\nsudo tar -xpf ~/machines-bak/arch1.tar --totals\n```\n\n## Backup Tools\n\nThe `tar` commands above may be not the smartest method, however, it's a proven robust method without any extra tool installations. Often,  simple is best.\n\nHowever, you may select various backup tools for more efficiency.\n\n[Synchronization and backup programs @ArchWIKI](https://wiki.archlinux.org/index.php/Synchronization_and_backup_programs)\n\nGit base [bup](https://github.com/bup/bup) looks good and new.\n\n## What you may consider to remove from the container OS\n\nAny hardeware dependent factors such as:\n\n- linux kernels with various drivers\n- `/etc/fstab`\n- `NetworkManager.service` of `systemd`\n\n## MIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fken-okabe%2Fwayland-desktop-container","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fken-okabe%2Fwayland-desktop-container","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fken-okabe%2Fwayland-desktop-container/lists"}