Fediventure Overview

Welcome! This is the documentation for Fediventure, a project to bring an rc3-world like experience as a federated system across *spaces.

We base on WorkAdventure and currently develop multiple parallel approaches to federate WorkAdventure. However, you can already deploy your own Prototype instance for your *space and start inviting people over, working on maps, etc.

For further information about the Prototype, and future development of Fediventure, keep on reading. Otherwise, head on over to the Prototype section to see how you can get it running today.

Prototype

This approach to Fediventure aims to get things running across *spaces as soon as possible. It currently mostly consists of working on the WorkAdventure JavaScript frontend, and a bare minimum of changes to the existing backend services so that you can host your own instance easily. To see how to get it running, head on over to the Prototype section.

Future work: matrixless and matrixful implementations

We are currently designing two concurrent implementations of Fediventure that would provide a full federation featureset:

cross-*space authentication and identity
simplified *space discovery
protocol extendability for per-*space extentions
cross-*space moderation and safety

These are actively developed on our issue tracker:

issues/1 - Matrixless federation protocol proposal
issues/xxx - Matrixful federation protocol proposal (no issue, fixme!)

Once both approaches are fully fleshed out, a decision to follow either one will be followed, and the Prototype will slowly transition to become either implementation.

Prototype

Each deployment consists of the following:

                     .- - - - - - - - - - - - - - - - -.
    .-------------.  :                                 :
    | web browser |  :             .-------------.     :
    |-------------| <--- HTTP ---> | proxy       |     :
    |  frontend   |  :             | (eg. nginx) |     :
    '-------------'  :             '-------------'     :
                     :          .----'|      |         :
                     :          |   .-'      |         :
                     :          v   |        |         :
                     :  .----------------.   |         :
                     :  |      maps      |   |         :
                     :  | (static files) |   |         :
                     :  '----------------'   |         :
                     :              |        |         :
                     :              v        |         :
                     :    .----------------. |         :
                     :    |   frontend     | |         :
                     :    | (static files) | |         :
                     :    '----------------' |         :
                     :                   .---'         :
                     :                   v             :
                     :          .------------------.   :
                     :          |      pusher      |   :
                     :          |     (node.js)    |   :
                     :          '------------------'   :
                     :                   ^             :
                     :                   | gRPC        :
                     :                   v             :
                     :          .------------------.   :
                     :          |     backend      |   :
                     :          |     (node.js)    |   :
                     :          '------------------'   :
                     :                                 :
                     : adventure.example.com           :
                     '- - - - - - - - - - - - - - - - -'

So, in other terms, the Fediventure Prototype is a self-contained distribution of WorkAdventure, that contains a common patchset across all instances of it. As the Matrixful/Matrixless proposals evolve, the Prototype will too, and will become a fully fledged federated instance within the protocol that is picked.

Installation

To install the Prototype, you can follow any of the following:

Install on NixOS, if this is what you're running on your production machine. This is the main recommended method of running Fediventure.
Install using OCI images, if running OCI images is your preferred production deployment approach (ie. if you want to use Docker/Kubernetes).
Install from scratch, if the above does not work for you. This is highly discouraged, instead we would prefer hearing from you why none of the above work for you.

Install on NixOS

This describes how to run the Fediventure Prototype on NixOS hosts. This is a production-ready deployment that is the recommended way of running the Prototype.

Note: this will only work on NixOS hosts, not Nix installed on other distributions / operating systems.

Licensing

The Fediventure code is licensed under the GNU AGPL 2.0, and it bases on WorkAdventure, which itself is license under the GNU AGPL 2.0 with The Commons Clause. Make sure you understand what this entails.

The authors' interpretation with regards to Nix(OS) code is that imports from your configuration are derivative works of the Fediventure NixOS modules and other Nix code.

However, as the Nix(OS) configuration only executes at system configuration build time, and is not part of the served Fediventure instance, you do not need to publish it.

On the other hand, any changes to the code that runs within Fediventure services will need to be published - be it WorkAdventure components or wrapper scripts within Nix derivations. Keep in mind the Commons Clause condition that WorkAdventure is distributed with.

Prerequisites

A machine running NixOS with publicly reachable 80/443 ports (or an equivalent reverse proxy setup)
A domain pointed to the machine (currently we only support running all components of the Prototype under a single domain name).

In the rest of this document, we will show you how to install the Prototype to serve Fediventure on adventure.example.com.

Creating a Fediventure module file

First, prepare a new NixOS module file for your fediventure deployment. This makes it easier to follow this guide.

$ vi /etc/nixos/fediventure.nix

With the following content:

{ config, pkgs, ... }: {
   # Empty...
}

And import it somewhere within your main configuration.nix:

$ vi /etc/nixos/configuration.nix
[...]
{
  imports = [
    # Include the result of the hardware scan.
    ./hardware-configuration.nix
    # Include the fediventure config.
    ./fediventure.nix
  ];

[...]

Now, nixos-rebuild switch should succeed, and the result should be a no-op.

Importing the Fediventure git repository

As the Fediventure code lies within it's own repository, you will need to import it:

$ vi /etc/nixos/fediventure.nix

{ config, pkgs, ... }: let
  fediventure = builtins.fetchGit {
    url = "https://gitlab.com/fediventure/fediventure.git";
    rev = "03b9a1ab6a7b0e56fcd2ce99970c762801e02e64";
  };
  sources = import "${fediventure}/nix/sources.nix";
  workadventure-nix = import (sources.workadventure-nix + "/overlay.nix");
in {
  imports = [
    "${fediventure}/ops/nixos/modules/workadventure/workadventure.nix"
  ];
  nixpkgs.overlays = [
    workadventure-nix
  ];
}

This performs a bunch of Import-From-Derivation magic to overlay workadventure-nix onto your system nixpkgs and to import fediventure NixOS module definitions.

nixos-rebuild switch should continue to switch and be a no-op, but you should be able to also add pkgs.workadventure.back to your environment.systemPackages if you want to check that everything works.

Configuring Fediventure

Now you're ready to start the workadventure services! In your configuration (either in fediventure.nix next to nixpkgs.overlays, or anywhere in your configuration.nix set the following:

services.nginx.virtualHosts."adventure.example.com" = {
  enableACME = true;
  forceSSL = true;
};

services.workadventure.instances."adventure.example.com" = {
  nginx.domain = "adventure.example.com";
};

Configure nginx/ACME accordingly - the above configuration should work fine for publicly-facing hosts.

nixos-rebuild switch and that's it, you should be able to visit https://adventure.example.com in your browser.

Custom maps

By default, the instance will serve the default WorkAdventure maps from upstram at /maps. To disable this behaviour:

services.workadventure.instances."adventure.example.com" = {
  # previously set options ...
  nginx.serveDefaultMaps = false;
};

To configure which map to load by default, set:

services.workadventure.instances."adventure.example.com" = {
  # previously set options ...
  frontend.urls.maps = "https://maps.example.com/";
};

The client will then load https://maps.example.com/Floor0/floor0.json by default. You will have to set up maps.example.com yourself to serve the map static files, with appropriate CORS headers set to allow access from your WA domain.

TODO(q3k): make Floor0/floor0.json configurable!

TODO(q3k): describe map serving on NixOS

Install using OCI (Docker) images

We provide the following OCI images:

registry.gitlab.com/fediventure/fediventure/workadventureback:main - backend
registry.gitlab.com/fediventure/fediventure/workadventurefront:main - frontend
registry.gitlab.com/fediventure/fediventure/workadventurepusher:main - pusher

TODO(q3k): describe how to configure/deploy this

Install from scratch

TODO(q3k)

Fediventure Docs