xrforge/manyfold

Manyfold container

The XRForge-serverimage is a pre-configured Manyfold container (reproducably via nix dockertools). It also contains some extra's, to better fit an XR audience & enable community libraries.

To run the container, see the docker-cmd below sysadmin documentation of the manyfold project.

$ docker run -t xrforge docker.io/coderofsalvation/xrforge:latest

To persist data:

$ mkdir mnt config
$ docker run -t xrforge docker.io/coderofsalvation/xrforge:latest -v ./mnt:/mnt -v ./config:/config

Build & Run the container-image

NOTE: nix is used to promote reproducability-over-repeatability

$ 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 FEDERATION=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

To preserve your uploaded models, add the experiences as a docker volume-flag, for example:

$ mkdir experiences
$ manyfold/cli/manyfold run -v ./experiences:/mnt/experiences

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
AFRAME_VERSION	1.7.0	AFRAME version
GODOT_VERSION	4.4.1-stable	godot editor version
GODOT_TEMPLATE_ZIP	``	godot template zip URL or file (default is empty godot project)
RUNTESTS	0	set to 1 to run XRForge related /test scripts
DEV	``	enable development mode (disables caching, sets bin/dev as entrypoint)
NO_PUBLIC_ONLY	``	disable public only models
NO_OVERLAYFS	``	disable the filesystem overlay mechanism
NO_DEFAULTDB	``	disable the default xrforge db (activates manyfold installer)
NO_ASSETS	``	disable downloading assets from xrfragment.org repository
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_HOST	http://localhost:3215	host adress which other hosts can use to access the federate drive
FEDERATE_DRIVE_PATH	/mnt	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 network-drives as manyfold libraries.

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 rclone_automount-cmd) during container boot.

• TIP2: use env-var RCLONE_REMOTE to mount only one specific remote (in case of a combined or 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, 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.

Customization

See the manyfold repository. For a quick dev-environment run:

$ mkdir /dev
$ manyfold/cli/manyfold.sh run -e DEV=1