8.2 KiB

Raw Permalink Blame History

xrsh

click here for the website / hosted repo

XRSH Manual

Documentation for XRSH users can be found here

TIP: this is also available by typing ctrl/cmd+a+0 or man xrsh inside XRSH

Wiki / Roadmap

See the wiki here

Install

NOTE: installation is optional: just surf to the public version here

For local use: download the crossplatform xrsh.com executable [checksum]:

[linux/mac only] run chmod +x xrsh.com in the console
run ./xrsh.com in the console
xrsh opens in your browser at https://127.0.0.1:8080
profit!

pass -p XXXX to specify port (default:8080)

Installation guides

run standalone binary

Download xrsh.com
optional: run unzip xrsh.com to verify repository contents
run chmod +x xrsh.com in your console (only linux/mac)
run ./xrsh.com in (any) shell
Profit! ✔

install using nixos

NIX is a convenient way to install or develop xrsh:

nix-shell -p xrsh thttpd
run it (thttpd -p 8080 -d /nix/store/5q4vd50gmh52jh48z62ln1j05xzfh1fz-xrsh-0.142 e.g.)
point your browser to localhost:8080
profit!

run OCI container [podman/docker]

$(which podman || which docker) run -p 8080:8080 docker.io/coderofsalvation/xrsh
point your browser to localhost:8080
profit!

NOTE 1: to add files use the -D <dir> overlay webroot parameter.

NOTE 2: to enable SSL and add (iso)file try something like this:

$ mkdir data
$ cp ../xrsh.iso data/. # copy custom iso
$ $(which podman || which docker) run -p 8080:8080 -v data/cert:etc/cert -v data:/data docker.io/coderofsalvation/xrsh /xrsh.com -D /data -c 0 -C /etc/cert/cert.pem -K /etc/cert/key.pem

or as an exercise in constructive laziness setup a reverse proxy like zoraxy, go-proxy, [droxy], caddy or nginx-reverse-proxymanager.

run from codeberg.org

(codeberg.org is a nonprofit-backed forgejo instance)

create a repository on codeberg.org
git push the xrsh repository to it
create a pages branchclone
push it to the codeberg repository
profit! it is now live

more info: https://docs.codeberg.org/codeberg-pages/

run from selfhosted forgejo/gitea instance

clone the xrsh xrsh repository locally
create a repo on your forgejo instance
git push the xrsh to it
in your forgejo (docker/nix)-instance symlink it to the public folder (*)
point your browser to https://yourforgejo.org/assets/xrsh

* = for example: ln -f git/repositories/yourusername/xrsh gitea/public/assets/.

optionally customize the xrsh yunohost package with your own ISO

install in yunohost

search for xrsh in the yunohost application catalog
click install
profit!

optionally customize the xrsh yunohost package with your own ISO

install with systemd

Create a new systemd service file (sudo nano /etc/systemd/system/xrsh.service e.g.)
Specify the ExecStart directive to run the xrsh ([Service]\ExecStart=/path/to/xrsh.com -p 8080 e.g.).
Enable the service (sudo systemctl enable xrsh.service e.g.)
Start the service (sudo systemctl start xrsh.service).
Verify the service: sudo systemctl status xrsh.service or netstat -tuln.

run from github

Sigh..good old github times (RIP)..
It used to be a simple webinterface around git in 2008.
These days running a forgejo/gitea instance + CI is literally one cmd away (or hosted by codeberg.org.

Developers

Make sure to clone the repo including submodules (the xrsh-com repo)

$ git clone --recurse-submodules https://forgejo.isvery.ninja/xrsh/xrsh
$ cd xrsh
$ nix-shell  # optional but adviced (to get up and running instantly)

Now serve the repo from a HTTPS webserver (for example run ./make dev)

Eventhough a custom ISO-image can be built, XRSH is buildless software.
The crossplatform binary is just a zip-file with the source (using https://redbean.dev):

build using shellscript

Run ./make standalone to package everything into xrsh.com

build using nix

nix-build -E "with import <nixpkgs> { }; callPackage ./nix/xrsh-package.nix"
optionally see the other nix-files in nix-folder

launch different .iso / modify files

You can specify a different .iso file in various ways:

open the xrsh.com as a zip (drag-drop into a zip-manager, or add .zip extension)
method 1: overwrite xrsh.iso
method 2: open src/index.html and change isoterminal="iso: ./../xrsh.iso" to another file/URL

see developer-section below on building your own iso

development of components (src/com) takes places in this git submodule
development of xrsh.iso takes places in this gitsubmodule

IMPORTANT: existing AFRAME apps can embed a barebones XR terminal / REPL like this:

<html>
    <head>
        <script src="https://aframe.io/releases/1.6.0/aframe.min.js"></script>
        <script src="https://xrsh.isvery.ninja/xrsh.js"></script>
    </head>
    <body>
      <a-scene>
          <a-entity isoterminal position="0 1.6 -0.3"></a-entity>
      </a-scene>
      <script>
        document.querySelector('a-scene').addEventListener('isoterminal_init', function(e){

          // (OPTIONAL) override/extend bootmenu-array with your own REPL(s)
          //            see com/isoterminal/feat/boot.REPL.*.js for examples
          ISOTerminal.prototype.boot.menu.push({
            key: "f",
            title: (opts) => `other awesome NLnet FOSS projects ❤️`,
            init: function( mainmenu ){
              window.open('https://nlnet.nl/project/current.html','_blank')
              // return to main menu
              mainmenu()
            },
            keyHandler: function(ch){
              this.send("\n\ryou typed:"+ch) // write to term
            }
          }) 

        })

        // AFRAME exposes THREE too
        console.log(THREE)

      </script>
    </body>
</html>

> this portable version runs without the ISO (which requires wasm-files, longer loadingtimes e.g.)

Funding

This project is funded through NGI0 Entrust, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.

Inspired by

mimetype hooks: Future of Text's
xterm
xr-terminal of Mauve (an amazingly talented dev)
Fabien Beneout's PIM (the WIKI containing all secrets & ideas in life)

8.2 KiB Raw Permalink Blame History