xrforge/manyfold/README.md

# Manyfold container

The XRForge-serverimage is a pre-configured [Manyfold](https://manyfold.app) container (reproducably via [nix](https://nixos.org) dockertools).
It also contains some extra's, to better fit an XR audience & enable community libraries.

> To run the container, see the [sysadmin](https://manyfold.app/sysadmin/) documentation of the [manyfold](https://github.com/manyfold3d/manyfold) project.

# Build/Run the container-image

```bash
$ git clone --recurse-submodules --depth 1 https://codeberg.org/coderofsalvation/xrforge.git 
$ cd xrforge
$ docker load < $(nix-build nix/docker.nix)
$ manyfold/cli/manyfold run 

[xrforge] podman detected..starting OCI container                                                        
+ /run/current-system/sw/bin/podman run -p 8790:3214 -p 8791:3215 --name xrforge -e SECRET_KEY_BASE=lkjwljlkwejrlkjek34k234l -e DATABASE_ADAPTER=sqlite3 -e SUDO_RUN_UNSAFELY=enabled -e MULTIUSER=enabled -e FEDER
ATION=enabled -e THEME=vapor -e HOMEPAGE=/models -e FEDERATE_DRIVE_CACHE=5s -v ./xrfragment/assets:/mnt/assets/xrfragment/#1 --cap-add SYS_ADMIN --security-opt apparmor:unconfined --device /dev/fuse xrforge
[xrforge] booting...                                                                                     
[xrforge] applying filesystem overlay                                                                    
sending incremental file list                                                                            
...
```

> NOTE: if you don't want the default XR Fragments asset-library, omit `--recurse-submodules` in the git cmd.

# Extra environment-variables

| environment variable  | default      | info                   |
|-----------------------|--------------|------------------------|
| `APPNAME`             | `manyfold`   | manyfold instance name |
| `HOMEPAGE`            | `/models`    | show '/models' URL as homepage (use `/` for manyfold default) |
| `THEME`               | `default`    | bootstrap theme        |
| `RUNTESTS`            | `0`          | set to `1` to run XRForge related [/test](test) scripts |
| `NO_OVERLAYFS`        | ``           | disable the filesystem overlay mechanism |
| `NO_DEFAULTDB`        | ``           | disable the default db (activates manyfold installer) |
| `NO_DELETEBIGFILES`   | ``           | disable deleting big files which are older than 5 days and bigger than ($currentyear-2020) MB's |
| `NO_PACKAGEALL`       | ``           | don't package all experiences every hour to /usr/src/app/public/experiences.zip |
| `RCLONE_REMOTE`       | ``           | specify **single** rclone remote name (without semicolon) to mount (default: mount all rclone remotes)|
| `UPLOAD_PATH`         | `/mnt/experiences`| specify default library where user-files are uploaded (regular dir or mounted rclone path) |
| `FEDERATE_DRIVE_PATH` | `/mnt/experiences`| serve path over HTTP (so other instances can add it as a remote). Specify `0` to disable |
| `FEDERATE_DRIVE_PORT` | `3215`       | specify default library where user-files are uploaded (regular dir or mounted rclone path) |
| `FEDERATE_DRIVE_USER` | ``           | specify HTTP AUTH credentials (`user` e.g.) for restricted sharing |          
| `FEDERATE_DRIVE_PW`   | ``           | specify HTTP AUTH credentials (`pass` e.g.) for restricted sharing |          
| `FEDERATE_DRIVE_CACHE`| `1m0s`       | specify interval to re-check all models/directories |
| `FEDERATE_DRIVE_KEY`  | ``           | specify path to TLS PEM private key file  (`-v ./key.pem:/key.pem -e FEDERATE_DRIVE_KEY=/key.pem` dockerflag e.g.) |
| `FEDERATE_DRIVE_CERT` | ``           | specify path to TLS PEM public key certificate/CA/intermediate file (`-v ./cert.pem:/cert.pem -e FEDERATE_DRIVE_KEY=/cert.pem` dockerflag e.g.) |

> NOTE: if you have nix installed, you can easily try out environment-flags by running: `docker load < $(nix-build nix/docker.nix) && manyfold/cli/manyfold run -e RUNTESTS=1` e.g.

# Default database / admin login

* email: `xrforge@localhost`
* login: `xrforge`
* password: `xrforge!1`

> please modify the password in the settings screen of the webinterface.

# Filesystem overlay-mechanism

The server-image will boot `manyfold/cli/manyfold.sh boot` and check for directory `/manyfold` (in the container).
When found, it uses the files in there instead (`/manyfold/usr/src/app/public/404.html` instead of `/usr/src/app/public/404.html` e.g.).

# Federated libraries

Besides ActivitPub, XRForge allows federating manyfold libraries too, which allows manyfold libraries to:

* be mounted as a network drive on their desktop-machine (3D editor export-to-library)
* scale horizontally across instances:

```
                                                                       
   ┌────────────────────────┐              ┌────────────────────────┐  
   │                        │              │                        │  
   │      server instance A │              │      server instance B │  
   │                        │              │                        │  
   │ ┌──────────────────┐   │   rclone     │ ┌─────────────────┐    │  
   │ │ library          │   │              │ │ library         │    │  
   │ │                  ┼───┼──────────────┼─┤                 │    │  
   │ │                  │   │ http-drive   │ │                 │    │  
   │ │                  │   │              │ │                 │    │  
   │ └──────────────────┘   │              │ └─────────────────┘    │  
   │                        │              │                        │  
   └────────────────────────┘              └────────────────────────┘  
                                                                       
        READ / WRITE                               READ-ONLY           

```

It does this by automatically mapping [rclone](https://rclone.org) network-drives as manyfold libraries.

![](https://i.imgur.com/4VMF3CQ.png)

To enable rclone to mount **readonly** network drives (=remotes), the container must be run with FUSE-device support.
The quickest way is:

1. create directory `./manyfold/root/.config` outside of the container
2. add `-v ./manyfold/root/.config:/root/.config --cap-add SYS_ADMIN --security-opt apparmor:unconfined --device /dev/fuse` to the docker cmd 
3. now federate XRForge libraries by running `docker exec -it xrforge rclone config create myhttp http url=https://xrforgeinstanceB.com user=myuser pass=$(rclone obscure mypassword)` in a running container
4. profit! 

**Default behaviour**: your drives will/should get automagically mounted **readonly** and added as a library automagically (by [manyfold.sh](cli/manyfold.sh) `rclone_automount`-cmd) during container boot.

* TIP2: use env-var `RCLONE_REMOTE` to mount only one specific remote (in case of a [combined](https://rclone.org/combine/) or [union](https://rclone.org/union/) rclone remote e.g.).
* TIP2: use **alphanumeric** names for rclone remotes (manyfold libraries choke on dot- or other special-characters)

By default environment-flag `FEDERATE_DRIVE_PATH` will share path `/mnt/experiences` as an open web directory.
Make sure that the URL (and credentials if configure) of step 3 are setup properly, so it matches your reverse proxy/ or SSL configuration (via `FEDERATE_DRIVE_CERT` and `FEDERATE_DRIVE_KEY` flags)

# Git libraries

XRForge also automatically maps git-repositories as libraries.
Repositories are detected via the `/mnt` directory, which can be fed as a **volume** via the docker cmd:

```
$ cd xrforge
xrforge $ mkdir mnt && cd mnt
xrforge/mnt $ git clone https://codeberg.org/my/repo
xrforge/mnt $ ls repo

john/#1023/foo.glb
john/#1023/bar.glb
mary/#103/flop.glb

xrforge $ docker run xrforge ... -v ./mnt/repo:/mnt/repo ... 
```

> **NOTE**: repositories need to respect XRForge's `{creator}/{modelId}` modelpath. This automatically creates creators/models in the database. This does not mean creators can automatically log in (no passwords are set), which should be fine for most archive-like purposes.

# Unixy event hooks 

Until WebEvents/WebSub [gets supported on a REST-level in manyfold](https://github.com/orgs/manyfold3d/projects/4/views/1?filterQuery=Pub&pane=issue&itemId=108834509&issue=manyfold3d%7Cmanyfold%7C4097), things like boot-phase, scheduler and file-changes can be reacted up via the `/root/hook.d` directory:

```
$ ls /root/hook.d
boot
daily
hourly
inotify_CREATE
inotify_MODIFY
```

You can put scripts in there, which are fired when needed.

> Example: [manyfold/root/hook.d/daily/delete_big_files.sh] is triggered daily to cleanup files which exceed a certain age/size.

Currently inotify events (`inotify_MODIFY` e.g.) are triggered for local file-changes (`/mnt/experiences` e.g.).
In theory, federated drives can still be reacted upon, but by integrating with XRForge's ActivityPub (**Follow** feature e.g.)

> Perhaps in the future this will also work for rclone remotes, by writing a `hourly`-script which scans them and fires `inotify_MODIFY` accordingly.