webtop ("web desktop") is a simple solution to run a Linux operating system on your existing Windows/MacOS/Linux computer. This allows a wide range of users to experience using a Linux desktop and terminal environment without the complexity of dual-booting their machine. After installation, you should be able to easily access WebTop via your browser. Your files are synchronized between the WebTop and your current operating system via a shared data/ folder.
- Beginner Friendly Guide to
webtop webtopfor ✨Advanced Users✨- 🚨Critical Usage Notes🚨
- 🔨Troubleshooting Common Issues🔨
- Design and Rationale (for those interested)
This section provides a beginner-friendly guide to installing and using webtop.
❗If you are new to Docker or Git, please click on the relevant OS logo below to access the installation guide for your operating system.
Please do not continue past this point if you're unfamiliar with Git or Docker! Use the guides above.
If you are already familiar with these tools, you can skip to the Advanced Users section.
This section assumes you are familiar with the terminal, git, and Docker.
❗If you are new to these tools, please refer to the beginner-friendly guide above.
- Docker: Ensure you have Docker installed and running on your system. You can download it from Docker's official website.
- Git: Make sure you have Git installed. You can download it from Git's official website.
- Terminal: Familiarity with terminal commands is assumed. You will need to use the terminal (i.e., Command Prompt on Windows, Terminal on macOS, or bash on Linux) to run commands.
-
Clone the repository to your local machine using
git clone [email protected]:learn-compsci/webtop.git. -
Navigate to the cloned repository folder in your terminal:
cd webtop -
Start
webtopusing Docker Compose:docker compose up
-
Open your browser (e.g., Chrome/Firefox/Safari) and go to
localhost:3000. You should see a Linux desktop interface.
-
Updating Webtop: If we release a new version of
webtop, you can update it by running the following commands in thewebtopfolder:docker compose pull docker compose build --no-cache
Before using webtop, please read the following important notes regarding the webtop environment:
-
Data Sharing The files you create on
webtopare mostly automatically shared/synced to thedata/folder that should be created. -
Data persistence: The
webtopenvironment only guarantees that files in yourwebtop's home directory (~/i.e.,/config) are retained on each reboot. All files in other locations might not be preserved on container shutdown. -
System Wide Applications: If you install applications system-wide, they may not be available the next time you start
webtop(due to the above behavior).- You can install applications locally (within
~/), or use proot-apps to do this, but we try to install everything that you need from the start.
- You can install applications locally (within
This section provides solutions to common issues you might encounter while using webtop.
Ports are how applications communicate over the network, and each port can only be used by one application at a time. If you see an error like failed to bind host port for 0.0.0.0:3000, that means you might already have an application running on that port.
Solution:
- Go to the
docker-compose.ymlfile in this folder. - Under
ports, change the3000:3000to e.g.,3005:3000, where3005is the new port number on your existing operating system. - Now you can use
localhost:3005to access WebTop.
A daemon is a background program that runs continuously and handles requests. If you see an error like Cannot connect to the Docker daemon, it usually means Docker is not running on your system.
Solution:
- Windows/Mac: Open Docker Desktop and ensure it is running. You might have to restart your computer.
- Linux: Start Docker with
sudo systemctl start dockerorsudo service docker start.
Copy-pasting between your host machine and the WebTop environment may sometimes not work as expected. In these cases, follow the steps below to copy and paste text between your host machine and the WebTop environment (or vice-versa).
Note: we notice that copy-paste works on Chrome/Chromium based browsers, but often doesn't on Firefox
Solution:
- Open the menu by clicking the small blue bar on the left side of the screen.
- Open the "Clipboard" setting.
- The "Clipboard" text-box is synchronised with the "copy/paste" mechanism of WebTop. Whatever you put in there, you will be able to paste in the webtop environment. Likewise, whatever you copy in the WebTop environment, will appear in the "Clipboard" text-box.
- Note that to copy from the terminal in WebTop, highlight the stuff you want to copy, and press Ctrl-Shift-C (not Ctrl-C). Pasting is usually Ctrl-Shift-V.
webtop ("web desktop") aims to be a simple solution to run a Linux operating system and desktop environment (specifically: Debian 12 XFCE) within your existing operating system, and interact with the Linux desktop in your browser (no VirtualBox / VMWare / VNC client necessary!). Files are synchronized between the Linux instance and your current operating system via a shared data/ folder.
Getting non-Linux users to run a Linux operating system isn't always easy. Installing multiple operating systems on the same machine is an involved process. Virtual machines (VMs) are sometimes slow, and it's hard to run them with equal features across both Windows (x86 machines) and Mac (ARM machines) (we've tried!). Therefore, WebTop is what we think is the best way to experience Linux as a start.
webtop is heavily based on docker-webtop, which is itself based on the Selkies technology. Selkies is the primary technology that allows us to interact with the Linux desktop in a browser over VNC.