diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index be3fd49..eb5d3c9 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -33,7 +33,7 @@ on: GITHUB_RELEASE: type: boolean - description: 'Upload github release.' + description: 'Upload GitHub release.' required: true default: false diff --git a/README.md b/README.md index d9cb39a..6397288 100644 --- a/README.md +++ b/README.md @@ -8,54 +8,64 @@ WebVM is a server-less virtual environment running fully client-side in HTML5/We WebVM is powered by the CheerpX virtualization engine, and enables safe, sandboxed client-side execution of x86 binaries on any browser. CheerpX includes an x86-to-WebAssembly JIT compiler, a virtual block-based file system, and a Linux syscall emulator. -# How to: enable networking +# Enable networking -- Go to [https://webvm.io](https://webvm.io). -- Click "Tailscale Login" in the top right corner. +- Click "Connect via Tailscale" in the page header. - Log in to Tailscale (create an account if you don't have one). - If you are unfamiliar with Tailscale or would like additional information see [WebVM and Tailscale](/docs/Tailscale.md). -# How to: fork and deploy +# Fork and deploy + - Fork the repository. - Enable Github pages in settings. - Click on `Settings`. - Go to the `Pages` section. - Select `Github Actions` as the source. - Run the workflow. - - Go to the forked repository its Github actions tab. - - Accept the prompt. + - Go back to your fork. + - Click on `Actions. + - Accept the prompt. This is required only once to enable Actions for your fork. - Click on the workflow named `Deploy`. - - Click `Run workflow` and then once more `Run workflow`. + - Click `Run workflow` and then once more `Run workflow` in the menu. deploy_instructions_gif -After the action completes, which takes a few minutes, it will show the URL to the GitHub Pages site below the `deploy_to_github_pages` job. +After the workflow completes, which takes a few minutes, it will show the URL below the `deploy_to_github_pages` job. +# Local deployment + +From a local `git clone` + +- Download the `debian_mini` Ext2 image from [https://github.com/leaningtech/webvm/releases/](https://github.com/leaningtech/webvm/releases/) + - You can also build your own by selecting the "Upload GitHub release" workflow option. + - Plase the image in the repository root folder. +- Edit `index.html` + - Replace the `UID`/`GID` variables with `1000` + - Replace `DEVICE_TYPE` with `"bytes"` + - Replace `IMAGE_URL` with the name of the Ext2 image. For example `"debian_mini_20230519_5022088024.ext2"` +- Start a local HTTP server +- Enjoy your local WebVM. + # Bugs and Issues Please use [Issues](https://github.com/leaningtech/webvm/issues) to report any bug. Or come to say hello / share your feedback on [Discord](https://discord.leaningtech.com). -# Browsers support - -WebVM and CheerpX are compatible with any browser, both Desktop and Mobile, provided support for [SAB](https://caniuse.com/sharedarraybuffer), [IndexedDB](https://caniuse.com/indexeddb), and the device having enough memory. - # More links -- [Do: WebVM](https://webvm.io) -- [Read: WebVM](https://leaningtech.com/webvm-server-less-x86-virtual-machines-in-the-browser/) -- [Read: WebVM + Tailscale networking](https://leaningtech.com/webvm-virtual-machine-with-networking-via-tailscale/) -- [Learn: WebVM](https://leaningtech.com/webvm) -- [Watch: WebVM at GitNation](https://www.youtube.com/watch?v=VqrbVycTXmw) +- [WebVM: server-less x86 virtual machines in the browser](https://leaningtech.com/webvm-server-less-x86-virtual-machines-in-the-browser/) +- [WebVM: Linux Virtualization in WebAssembly with Full Networking via Tailscale](https://leaningtech.com/webvm-virtual-machine-with-networking-via-tailscale/) +- Reference GitHub Pages deployment: [Mini.WebVM](https://mini.webvm.io) +- [Crafting the Impossible: X86 Virtualization in the Browser with WebAssembly](https://www.youtube.com/watch?v=VqrbVycTXmw) Talk at JsNation 2022 # Thanks to... This project depends on: -- CheerpX, made by [Leaning Technologies](https://leaningtech.com) for the virtualization part +- CheerpX, made by [Leaning Technologies](https://leaningtech.com) for x86 virtualization and Linux emulation - xterm.js, [https://xtermjs.org/](https://xtermjs.org/), for providing the Web-based terminal emulator - [Tailscale](https://tailscale.com/) for the networking component -- [lwIP](https://savannah.nongnu.org/projects/lwip/) for the TCP/IP stack, compiled to the Web by [Cheerp](https://github.com/leaningtech/cheerp-meta) +- [lwIP](https://savannah.nongnu.org/projects/lwip/) for the TCP/IP stack, compiled for the Web via [Cheerp](https://github.com/leaningtech/cheerp-meta) # License Copyright (c) Leaning Technologies Limited. All rights reserved. diff --git a/docs/Tailscale.md b/docs/Tailscale.md index ffd66dd..a4f6414 100644 --- a/docs/Tailscale.md +++ b/docs/Tailscale.md @@ -1,12 +1,13 @@ -# Enabling networking +# Enable networking + - In order to access the public internet, you will need an Exit Node. See [Tailscale Exit Nodes](https://tailscale.com/kb/1103/exit-nodes/) for detailed instructions. - ***Note:*** This is not required to access machines in your own Tailscale Network. -- depending on your network speed, you may need to wait a few moments for the Tailscale Wasm module to be downloaded. +- Depending on your network speed, you may need to wait a few moments for the Tailscale Wasm module to be downloaded. **When all set:** - Log in with your Tailscale credentials. -- Go back to the WebVM tab. `Connect to Tailscale` should be replaced by your IP address. -- Start firing network requests! +- Go back to the WebVM tab. +- `Connect via Tailscale` should be replaced by your IP address. # Log in to Tailscale with an Auth key @@ -18,4 +19,4 @@ It is recommended to use an ephemeral key. # Log in to a self-hosted Tailscale network (Headscale) - Add `#controlUrl=` at the end of the URL. -- You can combine this option with `authKey` with a `&`: `#controlUrl=&authKey=`. \ No newline at end of file +- You can combine this option with `authKey` with a `&`: `#controlUrl=&authKey=`.