# xrsh

<img src='xrsh.svg' width="25%"/>

## [click here for the website / hosted repo](https://xrsh.isvery.ninja)

## XRSH Manual 

Documentation for XRSH users can be found [here](https://forgejo.isvery.ninja/xrsh/xrsh-buildroot/src/branch/main/buildroot-v86/board/v86/rootfs_overlay/root/manual.md)

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

## Wiki / Roadmap

See [the wiki here](https://forgejo.isvery.ninja/xrsh/xrsh/wiki/Home#milestones)

## Install 

> NOTE: installation is optional: just surf to the public version [here](https://xrsh.isvery.ninja)

For local use: download the crossplatform <a href="/xrsh.com" target="_blank">xrsh.com</a> executable [<a href="/xrsh.com.txt" target="_blank">checksum</a>]:<br>

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

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

### Installation guides

<details>
    <summary>run standalone binary</summary>

1. Download [xrsh.com](https://forgejo.isvery.ninja/xrsh/xrsh/raw/branch/main/xrsh.com)
2. optional: run `unzip xrsh.com` to verify repository contents
3. run `chmod +x xrsh.com` in your console (only linux/mac)
4. run `./xrsh.com` in (any) shell
5. Profit! ✔
</details>

<details>
    <summary>install using nixos</summary>

[NIX](https://nixos.org/) is a convenient way to install or develop xrsh:

1. `nix-shell -p xrsh thttpd`
2. run it (`thttpd -p 8080 -d /nix/store/5q4vd50gmh52jh48z62ln1j05xzfh1fz-xrsh-0.142` e.g.)
3. point your browser to `localhost:8080`
4. profit!
</details>

<details>
    <summary>run OCI container [podman/docker]</summary>

1. `$(which podman || which docker) run -p 8080:8080 docker.io/coderofsalvation/xrsh`
2. point your browser to `localhost:8080`
3. 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](https://github.com/tobychui/zoraxy), [go-proxy](https://github.com/yusing/go-proxy), [droxy], caddy or nginx-reverse-proxymanager.   

</details>

<details>
<summary>run from codeberg.org</summary>

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

1. create a repository on codeberg.org
2. `git push` the [xrsh repository](https://forgejo.isvery.ninja/xrsh/xrsh) to it
1. create a `pages` branchclone
2. push it to the codeberg repository 
3. profit! it is now live 

> more info: https://docs.codeberg.org/codeberg-pages/ 
</details>

<details>
<summary>run from selfhosted forgejo/gitea instance</summary>

1. clone the xrsh [xrsh repository](https://forgejo.isvery.ninja/xrsh/xrsh) locally 
2. create a repo on your [forgejo](https://forgejo.org) instance 
3. `git push` the xrsh to it 
4. in your forgejo (docker/nix)-instance symlink it to the public folder (*)
5. 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](https://forgejo.isvery.ninja/xrsh/xrsh_ynh) with your own ISO
</details>

<details>
    <summary>install in yunohost</summary>

1. search for xrsh in the [yunohost](https://yunohost.org) application catalog 
2. click install
3. profit!

> optionally customize the [xrsh yunohost package](https://forgejo.isvery.ninja/xrsh/xrsh_ynh) with your own ISO
</details>

<details>
    <summary>install with systemd</summary>

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

</details>

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

</details>

## Developers 

Make sure to clone the repo including submodules (the [xrsh-com](https://forgejo.isvery.ninja/xrsh/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.<br>
The crossplatform binary is just a zip-file with the source (using https://redbean.dev):

<details>
<summary>build using shellscript</summary>

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

</details>

<details>
<summary>build using nix</summary>

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

<details>
    <summary>launch different .iso / modify files</summary>

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

1. open the `xrsh.com` as a zip (drag-drop into a zip-manager, or add `.zip` extension) 
2. method 1: overwrite `xrsh.iso`
3. 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

</details>

* development of components (`src/com`) takes places [in this git submodule](https://forgejo.isvery.ninja/xrsh/xrsh-com)
* development of `xrsh.iso` takes places [in this gitsubmodule](https://forgejo.isvery.ninja/xrsh/xrsh-buildroot)

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

```html
<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.)

```

## Building your own ISO

As described in the [website documentation](https://xrsh.isvery.ninja/#Booting%20an%20ISO%20image) you could boot your own ISO distribution (TIP: a [filesystem overlay](https://xrsh.isvery.ninja/#Filesystem%20overlay) is easier):

```
$ git clone --recurse-submodules ssh://git@forgejo.isvery.ninja:8222/xrsh/xrsh.git 
$ git clone ssh://git@forgejo.isvery.ninja:8222/xrsh/xrsh-buildroot
$ cd xrsh
$ rm xrsh.iso && ln -fs ../xrsh-buildroot/dist/v86-linux.iso xrsh.iso
$ ./make dev 
```

You can read the [repo-README](https://forgejo.isvery.ninja/xrsh/xrsh-buildroot) about (re)building/modifying the iso

## Funding

This project is funded through [NGI0 Entrust](https://nlnet.nl/entrust), a fund established by [NLnet](https://nlnet.nl) with financial support from the European Commission's [Next Generation Internet](https://ngi.eu) program. Learn more at the [NLnet project page](https://nlnet.nl/project/xrsh).

[<img src="https://nlnet.nl/logo/banner.png" alt="NLnet foundation logo" width="20%" />](https://nlnet.nl)
[<img src="https://nlnet.nl/image/logos/NGI0_tag.svg" alt="NGI Zero Logo" width="20%" />](https://nlnet.nl/entrust)

## Inspired by

* [mimetype hooks](https://forgejo.isvery.ninja/xrsh/xrsh-buildroot/src/branch/main/buildroot-v86/board/v86/rootfs_overlay/root/hook.d/mimetype): [Future of Text's](https://github.com/TheElectronicLiteratureLab/spasca-fsbased-interrop-companion/)
* [xterm](https://invisible-island.net/xterm/)
* [xr-terminal](https://github.com/RangerMauve/xr-terminal) of Mauve (an amazingly talented dev)
* [Fabien Beneout's PIM](https://fabien.benetou.fr/) (the WIKI containing all secrets & ideas in life)