utopiah/biggu_s_gate
1
0
Fork 0
Code Issues 106 Pull Requests Packages Projects Releases Wiki Activity

Documenting how to setup a server #20

New Issue
Closed
opened 2025-09-18 07:24:23 +00:00 by utopiah · 26 comments
utopiah commented 2025-09-18 07:24:23 +00:00
Owner
Copy Link
No description provided.
utopiah added the Instance setup label 2025-09-18 07:24:23 +00:00
utopiah commented 2025-09-18 10:56:54 +00:00
Author
Owner
Copy Link

To be validated by local actors, e.g.

or more broadly in France

potentially even https://code.gouv.fr/sill/

To be validated by local actors, e.g. - https://www.domainepublic.net - https://nubo.coop - https://www.taurix.net or more broadly in France - https://www.chatons.org potentially even https://code.gouv.fr/sill/
utopiah added this to the NGI0 Commons Fund 2025-04 milestone 2025-09-18 12:00:35 +00:00
utopiah commented 2025-09-20 08:20:42 +00:00
Author
Owner
Copy Link

See also

  • index.html the main client-side page (with dependency on JXR core)
  • remixed.html remix browser
  • remixed_16_39_53_modifications.txt example of modication via URL
  • remixed_12345.json example of modication via JSON
  • wbjr_webxrservice_index.js backend server for WebDAV (saving) and express (client-side experience and remix browser)
See also * `index.html` the main client-side page (with dependency on [JXR core](https://git.benetou.fr/utopiah/text-code-xr-engine/)) * `remixed.html` remix browser * `remixed_16_39_53_modifications.txt` example of modication via URL * `remixed_12345.json` example of modication via JSON * `wbjr_webxrservice_index.js` backend server for WebDAV (saving) and express (client-side experience and remix browser)
utopiah commented 2025-09-24 12:14:17 +00:00
Author
Owner
Copy Link

Ideally would require the smallest amount of steps e.g

  • npm i (assuming package.json)
  • if npm is unavailable then suggesting to either install it, or rely on a container image, e.g. https://hub.docker.com/_/node/ which in turns does npm i
Ideally would require the smallest amount of steps e.g - `npm i` (assuming `package.json`) - if `npm` is unavailable then suggesting to either install it, or rely on a container image, e.g. https://hub.docker.com/_/node/ which in turns does `npm i`
utopiah commented 2025-09-27 09:11:40 +00:00
Author
Owner
Copy Link

Consider Gitpod (or self hostable, by me or others, not for the newcomer, equivalent) allowing for 1-click setup.

Consider Gitpod (or self hostable, by me or others, not for the newcomer, equivalent) allowing for 1-click setup.
utopiah commented 2025-11-16 23:31:11 +00:00
Author
Owner
Copy Link

Consider also utopiah/spasca-fot-sloan-q4#4 e.g. WebDAV via CopyParty. This can optionally rely ngrok but ideally without it nor cfssl as both are vendor dependent and centralized.

By default lacks permission management but enough to share and remix with relatively simple setup.

Note that this imply exploring avoiding wbjr_webxrservice_index.js entirely and trying instead to keep everything possible client side. This might mean user management done via WebDAV or here more specifically as CopyParty configuration :

  • index.html the main client-side page (with dependency on JXR core)
  • remixed.html remix browser
  • remixed/
    • remixed_16_39_53_modifications.txt example of modication via URL
    • remixed_12345.json example of modification via JSON
  • wbjr_webxrservice_index.js backend server for WebDAV (saving) and express (client-side experience and remix browser)
    • avoiding a whole CRUD backend to maintain, focusing on XR for pedagogy first
  • copyparty.conf for server side user rights
    • only some users (with WebDAV login/password) could
      • modify files like index.html
      • update a list of followed instances as URLs
    • registered users, non admin
      • update directories of modifications (no need for a database even as single .json file)
      • update metadata on modifications, e.g. comments, suggested modifications, etc
    • public
      • read modified content
Consider also https://git.benetou.fr/utopiah/spasca-fot-sloan-q4/issues/4 e.g. WebDAV via `CopyParty`. This can optionally rely `ngrok` but ideally without it nor `cfssl` as both are vendor dependent and centralized. By default lacks permission management but enough to share and remix with relatively simple setup. Note that this imply exploring avoiding `wbjr_webxrservice_index.js` entirely and trying instead to keep everything possible client side. This might mean user management done via WebDAV or here more specifically as CopyParty configuration : * `index.html` the main client-side page (with dependency on [JXR core](https://git.benetou.fr/utopiah/text-code-xr-engine/)) * `remixed.html` remix browser * `remixed/` * `remixed_16_39_53_modifications.txt` example of modication via URL * `remixed_12345.json` example of modification via JSON * ~~`wbjr_webxrservice_index.js` backend server for WebDAV (saving) and express (client-side experience and remix browser)~~ * avoiding a whole CRUD backend to maintain, focusing on XR for pedagogy first * `copyparty.conf` for server side user rights * only some users (with WebDAV login/password) could * modify files like `index.html` * update a list of followed instances as URLs * registered users, non admin * update directories of modifications (no need for a database even as single .json file) * update metadata on modifications, e.g. comments, suggested modifications, etc * public * read modified content
utopiah commented 2025-12-06 10:22:23 +00:00
Author
Owner
Copy Link

Consider who the audience is, even 1-liner with curl pulling a script from this repository might be too much for a non technical user.

Consequently in such a situation sticking to what is relying on the least amount of dependencies (e.g. npm i or "just" CopyParty or a Dockerfile) might be best.

Note that the first setups will be done on behalf of somebody running a workshop or even a classroom. This issue is to insure they can be independent before and after the workshop even if they might need to ask support from a technical colleague, e.g. the sysadmin of a school or a friend.

Consider who the audience is, even 1-liner with `curl` pulling a script from this repository might be too much for a non technical user. Consequently in such a situation sticking to what is relying on the least amount of dependencies (e.g. `npm i` or "just" CopyParty or a `Dockerfile`) might be best. Note that the first setups will be done on behalf of somebody running a workshop or even a classroom. This issue is to insure they can be independent before and after the workshop even if they might need to ask support from a technical colleague, e.g. the sysadmin of a school or a friend.
utopiah commented 2026-01-24 08:05:06 +00:00
Author
Owner
Copy Link

See also https://itsfoss.gitlab.io/post/how-to-create-a-simple-deb-debian-package/ for an relatively convenient way to deploy on Debian and thus on a lot of systems.

Set up a dedicated package repository, e.g. https://wiki.debian.org/DebianRepository/Setup using

  • apt-ftparchive where the .deb package is to generate the package list
  • echo "deb [trusted=yes] https://home.benetou.fr /" > /etc/apt/sources.list.d/biggu.list to add the repository
    • warning : this is NOT signed and verified thus a security risk
  • apt update && apt install biggu-s-gate to install

Current the test package is available as biggu_s_gate.deb at https://home.benetou.fr/biggu_s_gate.deb and depends on NodeJS. Note that it does NOT include a reverse proxy or a way to have an HTTPS server which is mandatory for WebXR. It is assumed, maybe incorrectly, that the person installing the package already has their own solution working. It could be interesting to provide an HTTPS server regardless on an unprivileged port with self-signed certificate.

See also https://itsfoss.gitlab.io/post/how-to-create-a-simple-deb-debian-package/ for an relatively convenient way to deploy on Debian and thus on a lot of systems. Set up a dedicated package repository, e.g. https://wiki.debian.org/DebianRepository/Setup using * `apt-ftparchive` where the `.deb` package is to generate the package list * `echo "deb [trusted=yes] https://home.benetou.fr /" > /etc/apt/sources.list.d/biggu.list` to add the repository * warning : this is NOT signed and verified thus a security risk * `apt update && apt install biggu-s-gate` to install Current the test package is available as biggu_s_gate.deb at https://home.benetou.fr/biggu_s_gate.deb and depends on NodeJS. Note that it does NOT include a reverse proxy or a way to have an HTTPS server which is mandatory for WebXR. It is assumed, maybe incorrectly, that the person installing the package already has their own solution working. It could be interesting to provide an HTTPS server regardless on an unprivileged port with self-signed certificate.
utopiah commented 2026-02-13 16:08:31 +00:00
Author
Owner
Copy Link

Running test instance on biggu.benetou.fr behind reverse proxy and self-hosted.

History of setup should be used as documentation too, i.e. :

  1. clone repository, copy data
  2. npm start after disabling HTTPS
  3. get certificate via certbot
  4. setup reverse proxy for new domain
  5. optionally link new domain from other starting points or documentation (e.g here) or local sharing via e.g. hmd.link
Running test instance on `biggu.benetou.fr` behind reverse proxy and self-hosted. History of setup should be used as documentation too, i.e. : 1. clone repository, copy data 2. `npm start` after disabling HTTPS 3. get certificate via certbot 4. setup reverse proxy for new domain 5. optionally link new domain from other starting points or documentation (e.g here) or local sharing via e.g. hmd.link
utopiah commented 2026-02-13 17:00:19 +00:00
Author
Owner
Copy Link

See nginx reverse proxy details https://github.com/networked-aframe/networked-aframe/issues/244 in particular

  location /socket.io {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
  }
  location /easyrtc {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
  }
See nginx reverse proxy details https://github.com/networked-aframe/networked-aframe/issues/244 in particular ```nginx location /socket.io { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; } location /easyrtc { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; } ```
utopiah commented 2026-02-14 05:52:50 +00:00
Author
Owner
Copy Link

Running 2nd test instance for federation testing more specifically on biggubis.benetou.fr

Much faster setup this time, went from ~1h to 15min. Relied on basic Dockerfile :

FROM debian:13
RUN apt update && apt install -y nodejs npm
COPY . /opt/biggu_s_gate
WORKDIR /opt/biggu_s_gate
CMD npm start

Note that federation between those 2 instances is not enabled yet but would initially focus on :

  • remixing between instances

and might not focus on the typical CRUD for users, completion, etc as it is important yet less fundamental. See #21

Running 2nd test instance for federation testing more specifically on `biggubis.benetou.fr` Much faster setup this time, went from ~1h to 15min. Relied on basic `Dockerfile` : ```dockerfile FROM debian:13 RUN apt update && apt install -y nodejs npm COPY . /opt/biggu_s_gate WORKDIR /opt/biggu_s_gate CMD npm start ``` Note that federation between those 2 instances is not enabled yet but would initially focus on : - remixing between instances and might not focus on the typical CRUD for users, completion, etc as it is important yet less fundamental. See #21
utopiah commented 2026-02-15 12:49:41 +00:00
Author
Owner
Copy Link

Delivery of (large) assets or packages could be done via P2P, e.g. WebSeed for BitTorrent.

Delivery of (large) assets or packages could be done via P2P, e.g. WebSeed for BitTorrent.
utopiah commented 2026-03-12 10:15:21 +00:00
Author
Owner
Copy Link

Periodically validated during workshops, see #23

Ideally done against a popular image, e.g. Raspberry Pi OS (64-bit) and listing here such steps.

Periodically validated during workshops, see #23 Ideally done against a popular image, e.g. [Raspberry Pi OS (64-bit)](https://www.raspberrypi.com/software/operating-systems/) and listing here such steps.
utopiah commented 2026-03-17 07:15:49 +00:00
Author
Owner
Copy Link

Practical way to run again after tinkering

cd ~/Prototypes/biggu_naf_new/ ; killall networked-aframe-server ; nohup npm start &

which allows

  • to run in the background, even after killing the current terminal,
  • replace any potentially running similar process (assuming single instance per current user),
  • log to be in output.log in the current directory.
Practical way to run again after tinkering `cd ~/Prototypes/biggu_naf_new/ ; killall networked-aframe-server ; nohup npm start &` which allows - to run in the background, even after killing the current terminal, - replace any potentially running similar process (assuming single instance per current user), - log to be in `output.log` in the current directory.
utopiah commented 2026-03-23 13:16:33 +00:00
Author
Owner
Copy Link

Note that if a reverse proxy is used in order to send (relatively large) screenshots as POST payload it has to be configured to allow it, see https://git.benetou.fr/utopiah/biggu_s_gate/src/branch/main/server/biggu_backend_express_naf_extension.js#L10 e.g. client_max_body_size 10M; in nginx.

Note that if a reverse proxy is used in order to send (relatively large) screenshots as POST payload it has to be configured to allow it, see https://git.benetou.fr/utopiah/biggu_s_gate/src/branch/main/server/biggu_backend_express_naf_extension.js#L10 e.g. `client_max_body_size 10M;` in nginx.
utopiah commented 2026-03-26 15:54:22 +00:00
Author
Owner
Copy Link

Not all dependencies are provided in the repository. Some have to be pulled manually, other are modified to work offline. Consequently what's currently recommended is to get (e.g. using wget) the required resources from the public test instance, namely https://biggu.benetou.fr.

Not all dependencies are provided in the repository. Some have to be pulled manually, other are modified to work offline. Consequently what's currently recommended is to get (e.g. using `wget`) the required resources from the public test instance, namely `https://biggu.benetou.fr`.
utopiah commented 2026-03-26 15:59:37 +00:00
Author
Owner
Copy Link

Current limitations from git clone then npm i :

  • missing key.pem / cert.pem files (has to be generated)
  • static directory is served from ../examples but should now be ../pages to match the repository
  • paths to files and directory isn't frontend/biggu_s_gate/ but should now be pages/
  • missing dependencies/ from https://biggu.benetou.fr/biggu_s_gate/dependencies/ can't be recursively fetched
  • npm i doesn't add js/ which is required from SocketIO

As fall back a huge (~350MB) dump is available at https://home.benetou.fr/biggu_naf_new_1774616968.tar but it contains much more than the minimal needed. It also contains certificate for the biggu.benetou.fr which consequently will not work for your instance and must be replaced. Still, if you absolutely urgently need all files in 1 location to run a workshop, this might be provide convenient. You can setup a RPi Zero as WiFi hotspot using https://fabien.benetou.fr/Cookbook/Electronics#SocialWebXRRPi0 for a fully offline workshop.

Consider also running the result in a browser with WebXR enabled and the check the network console to see what files might still be missing, in particular in XR mode with e.g. hands assets.

Current limitations from `git clone` then `npm i` : - missing key.pem / cert.pem files (has to be generated) - static directory is served from `../examples` but should now be `../pages` to match the repository - paths to files and directory isn't `frontend/biggu_s_gate/` but should now be `pages/` - missing `dependencies/` from https://biggu.benetou.fr/biggu_s_gate/dependencies/ can't be recursively fetched - `npm i` doesn't add `js/` which is required from SocketIO As fall back a huge (~350MB) dump is available at https://home.benetou.fr/biggu_naf_new_1774616968.tar but it contains much more than the minimal needed. It also contains certificate for the `biggu.benetou.fr` which consequently will not work for your instance and must be replaced. Still, if you absolutely urgently need all files in 1 location to run a workshop, this might be provide convenient. You can setup a RPi Zero as WiFi hotspot using https://fabien.benetou.fr/Cookbook/Electronics#SocialWebXRRPi0 for a fully offline workshop. Consider also running the result in a browser with WebXR enabled and the check the network console to see what files might still be missing, in particular in XR mode with e.g. hands assets.
utopiah commented 2026-03-29 05:47:08 +00:00
Author
Owner
Copy Link

Following the latest workshop the recommended archive to run a RPi Zero offline is https://home.benetou.fr/biggu_naf_new_1774763022.tar now in the most recent comment instead.

Following the latest [workshop](https://git.benetou.fr/utopiah/biggu_s_gate/wiki/Workshops) the recommended archive to run a RPi Zero offline is ~https://home.benetou.fr/biggu_naf_new_1774763022.tar~ now in the most recent comment instead.
utopiah commented 2026-03-29 05:55:10 +00:00
Author
Owner
Copy Link

Note that you do NOT need a RPi Zero. If you have a laptop with Linux or even an Android phone with Termux,

  1. install nodejs with npm,
  2. unpack that archive,
  3. run PORT=443 npm start in the new directly,
  4. open a hotspot and
  5. connect to it with a browser
Note that you do **NOT** need a RPi Zero. If you have a laptop with Linux or even an Android phone with Termux, 1. install `nodejs` with `npm`, 2. unpack that archive, 3. run `PORT=443 npm start` in the new directly, 4. open a hotspot and 5. connect to it with a browser
utopiah commented 2026-04-12 06:15:06 +00:00
Author
Owner
Copy Link

For Yunohost could try with https://doc.yunohost.org/en/dev/packaging/resources#nodejs

For Yunohost could try with https://doc.yunohost.org/en/dev/packaging/resources#nodejs
utopiah added the Review pending label 2026-04-13 12:46:10 +00:00
utopiah removed the Review pending label 2026-04-16 12:11:51 +00:00
utopiah added the Review pending label 2026-04-17 12:15:15 +00:00
utopiah commented 2026-04-27 08:08:15 +00:00
Author
Owner
Copy Link

Latest archive https://home.benetou.fr/biggu_naf_new_1777277248.tar

~Latest archive https://home.benetou.fr/biggu_naf_new_1777277248.tar~
utopiah commented 2026-04-27 19:41:11 +00:00
Author
Owner
Copy Link

Assets only archive https://home.benetou.fr/assets.tar radically smaller, from 500MB to 5MB but requires manual setup, namely currently :

git clone https://git.benetou.fr/utopiah/biggu_s_gate
cd biggu_s_gate/
npm i
npm run generate_certificate 
modify the paths in 
  https://git.benetou.fr/utopiah/biggu_s_gate/src/branch/main/server/easyrtc-server.js#L41 pages , not examples
  https://git.benetou.fr/utopiah/biggu_s_gate/src/branch/main/server/biggu_backend_express_naf_extension.js#L21 to pages , not examples for audio recording
  prior to static dir  https://git.benetou.fr/utopiah/biggu_s_gate/src/branch/main/server/easyrtc-server.js#L39 app.get('/', (req, res) => { res.redirect('/onboarding.html') } )
unpack https://home.benetou.fr/assets.tar in `pages/` # could be steps in package.json using wget
npm start # then open URL

npm run server_test # optionally in other terminal run
Assets only archive https://home.benetou.fr/assets.tar radically smaller, from 500MB to 5MB but requires manual setup, namely currently : ```bash git clone https://git.benetou.fr/utopiah/biggu_s_gate cd biggu_s_gate/ npm i npm run generate_certificate modify the paths in https://git.benetou.fr/utopiah/biggu_s_gate/src/branch/main/server/easyrtc-server.js#L41 pages , not examples https://git.benetou.fr/utopiah/biggu_s_gate/src/branch/main/server/biggu_backend_express_naf_extension.js#L21 to pages , not examples for audio recording prior to static dir https://git.benetou.fr/utopiah/biggu_s_gate/src/branch/main/server/easyrtc-server.js#L39 app.get('/', (req, res) => { res.redirect('/onboarding.html') } ) unpack https://home.benetou.fr/assets.tar in `pages/` # could be steps in package.json using wget npm start # then open URL npm run server_test # optionally in other terminal run ```
utopiah commented 2026-04-27 21:03:10 +00:00
Author
Owner
Copy Link

Latest archive https://home.benetou.fr/biggu_naf_new_1777323683.tar (all previous ones deleted)

Latest archive https://home.benetou.fr/biggu_naf_new_1777323683.tar (all previous ones deleted)
utopiah commented 2026-04-28 07:56:01 +00:00
Author
Owner
Copy Link

Follow https://git.benetou.fr/utopiah/biggu_s_gate/src/branch/main/documentation#administrator--developer for setup, namely, after cloning this repository :

npm i # install backend dependencies
npm run generate_certificate # generate self-signed certificates for local testing only
npm run get_and_install_assets # get assets, e.g. 3D models of hands, animated model and frontend dependencies
npm run start # start the backend
Follow https://git.benetou.fr/utopiah/biggu_s_gate/src/branch/main/documentation#administrator--developer for setup, namely, after cloning this repository : ``` bash npm i # install backend dependencies npm run generate_certificate # generate self-signed certificates for local testing only npm run get_and_install_assets # get assets, e.g. 3D models of hands, animated model and frontend dependencies npm run start # start the backend ```
utopiah commented 2026-04-28 11:37:51 +00:00
Author
Owner
Copy Link

Consider

if (forcehttps){
	webServer = https.createServer(credentials, app);
} else {
	webServer = http.createServer(app);
}

/*... */

webServer.listen(port, () => {
if (forcehttps)
    console.log("listening on https://localhost:" + port);
        else 
    console.log("listening on http://localhost:" + port);
});

to use with HTTPS=true npm start

cf https://git.benetou.fr/utopiah/biggu_s_gate/src/branch/main/server/easyrtc-server.js#L23

Consider ```javascript if (forcehttps){ webServer = https.createServer(credentials, app); } else { webServer = http.createServer(app); } /*... */ webServer.listen(port, () => { if (forcehttps) console.log("listening on https://localhost:" + port); else console.log("listening on http://localhost:" + port); }); ``` to use with `HTTPS=true npm start` cf https://git.benetou.fr/utopiah/biggu_s_gate/src/branch/main/server/easyrtc-server.js#L23
utopiah commented 2026-04-28 13:18:32 +00:00
Author
Owner
Copy Link

Setup tested and working on

  • RPi Zero running Debian 13.4
  • RPi 3 running Debian 13.4
  • x86_64 running Podman 4.3.1
  • arm64-v8a running Termux 1.45.0
Setup tested and working on - RPi Zero running Debian 13.4 - RPi 3 running Debian 13.4 - x86_64 running Podman 4.3.1 - arm64-v8a running Termux 1.45.0
utopiah commented 2026-04-28 14:54:22 +00:00
Author
Owner
Copy Link

To start on boot as an unpriviledged user

# in crontab
@reboot cd ~/biggu_s_gate && HTTPS=true /usr/bin/npm run start
To start on boot as an unpriviledged user ```bash # in crontab @reboot cd ~/biggu_s_gate && HTTPS=true /usr/bin/npm run start ```
utopiah removed the Review pending label 2026-05-29 12:37:04 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Beyond NLNet2025-04
Issues that do not have to be finished by the end of that NGI0 project but could be for follow-up
 Instance setup
Help the network of federated server grow.
Meta-data experience management
Experiences are done within a pedagogical context and thus keep tracking, even if entirely privately, of what has been completed or not should foster better learning.
 Process audits from NLNet network
Project management
Contribution, hosting, issues, etc
 Remixing
Remixing infrastructure for pedagogical immersive experiences
 Review pending
Strategic examples
Seeding examples to facilitate remixing, covering the broadest scope of what is both technically feasible and pedagogically impactful.
No Label Instance setup
Milestone
No items
No Milestone NGI0 Commons Fund 2025-04
Projects
Clear projects
No project
Assignees
Clear assignees
utopiah
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: utopiah/biggu_s_gate#20
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?