Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

MoodleNet

From MoodleDocs
Revision as of 08:29, 6 July 2023 by Alessandro Giansanti (talk | contribs) (Started V3 quickstart and config)

Moodlenet-logo.png

What is MoodleNet?

MoodleNet is a flexible Open Education Technology platform for curating collections of the best known Open Educational (and other) Resources. You'll find more general information in the MoodleNet user documentation.

If you are looking to get started as a MoodleNet developer, we recommend taking the MoodleNet for Developers course with Moodle Academy.

Current status

Take a look at MoodleNet releases in our Tracker.

Roadmap

Quick start guide

System Requirements

MoodleNet requires the followings to be available on your system

Notice that the current nodejs LTSs frameworks are nodejs ^18 and npm ^9

We tested so far with the previous LTSs nodejs ^16 and npm ^8

Make sure to have nodejs ^16 installed and you should get npm ^8 as well

Deploy an ArangoDB instance

You can choose how and where to deploy your ArangoDB, as long as it can be reached by MoodleNet process

An easy way to install ArangDB locally as a service is by using Docker[4] e.g. :

docker run -d --restart unless-stopped -e ARANGO_NO_AUTH=1 -p 8529:8529 --name=mn-3-db arangodb:3.10

Possibly tweaking some options as you like, e.g. mounting a volume or a directory for data or setting a password

Install MoodleNet

to install Moodlenet you simply need to issue the following npm command

npm create @moodlenet@latest path/to/installation/folder

this will install all MoodleNet core packages in the choosen folder

it will also create a default configuration file (default.config.json) and a default cryptographic key pair for the system (default.crypto.privateKey , default.crypto.publicKey)

Start MoodleNet process

To start MoodleNet issue the following command from within the installation directory

npm start

open your browser on http://localhost:8080

notice: on the first run the system will have to compile the webapp, so you'll get a 404 until ready. It should take a few minutes

MoodleNet configuration file

MoodleNet configuration file (default.config.json) holds all static system configs.

{
  "pkgs": {
    "@moodlenet/core": {
      "baseFsFolder": "/home/alec/MOODLENET/repo/moodlenet3/.dev-machines/1/fs",
      "instanceDomain": "http://localhost:8080",
      "npmRegistry": "https://registry.npmjs.org",
      "mainLogger": {
        "consoleLevel": "debug",
        "file": {
          "path": "./log/moodlenet.%DATE%.log",
          "level": "debug"
        }
      }
    },
    "@moodlenet/crypto": {
      "keys": {
        "alg": "RS256",
        "type": "PKCS8",
        "private": "/home/alec/MOODLENET/repo/moodlenet3/.dev-machines/default.crypto.privateKey",
        "public": "/home/alec/MOODLENET/repo/moodlenet3/.dev-machines/default.crypto.publicKey"
      }
    },
    "@moodlenet/arangodb": {
      "connectionCfg": {
        "url": "http://localhost:8529"
      }
    },
    "@moodlenet/http-server": {
      "port": 8080,
      "defaultRpcUploadMaxSize": "5MB"
    },
    "@moodlenet/ed-resource": {
      "resourceUploadMaxSize": "1.2GB"
    },
    "@moodlenet/simple-email-auth": {
      "newUserNotPublisher": false
    },
    "@moodlenet/email-service": {
      "nodemailerTransport": {
        "jsonTransport": true
      }
    },
    "@moodlenet/system-entities": {
      "rootPassword": "root"
    },
    "@moodlenet/react-app": {
      "noWebappServer": true
    }
  }
}

here's some relevant configs you may want to check and tweak

  • @moodlenet/arangodb.connectionCfg.url : the default config assumes you installed ArangoDB without password with standard port on the same host
  • @moodlenet/core.baseFsFolder : path to the system root folder for system filesystem persistency (better use absolute paths instead of relative to MoodleNet process cwd)
  • @moodlenet/core.instanceDomain : the public domain for your moodlenet instance (e.g https://myorg.moodle.net )
  • @moodlenet/email-service.nodemailerTransport : the nodemailer transport configuration for the system email service (notice, with the default configuration the system won't send any email, it will simply log them)

MoodleNet architecture

MoodleNet is a full stack TypeScript/JavaScript system using:

  • NodeJs
    • NPM Packages [5]
    • ESM Modules [6]
  • Browsers

MoodleNet development environment

Setup development environment

From the command line interface (CLI):

Ensure ArangoDB is running on localhost. You may use Docker with a command as below that can be tweaked as needed to ensure it is listening locally on port 8529:

docker run -e ARANGO_NO_AUTH=1 -p 8529:8529 --rm --name=mn3arango arangodb

Clone the repository, you may wish to fork it, but that's not required:

git clone https://gitlab.com/moodlenet/moodlenet.git

Change to the project's folder:

cd moodlenet

Install and initialize the project:

npm install

Install a development deployment:

npm run dev-install-backend [install dir name]

We have used "my-dev" as [install dir name] in the following instructions.

You’ll find the newly created dev-installation in .dev-machines/my-dev and can create as many dev installations as you wish.

Run development backend:

npm run dev-start-backend my-dev

The first run of the system takes some time to install.

Once installed, browse http://localhost:8080

Questions? Please take a look in the MoodleNet Community and Tracker for answers or to ask for help.

The moodlenet extension package template

You can use core MoodleNet development environment and processes to develop your packages.

We recommend to start understanding the extension framework tweaking the template package “my-moodlenet-mjs-pkg-template” you’ll find it in the folder “packages”.

It is written in Javascript (EMS) instead of Typescript for a better understanding by newcomers.

Using typescript for package development is strongly recommended, as ts-experienced-devs will take advantage of the strongly-typed framework. However this requires good typescript knowledge, and some measures and ceremonies as all MoodleNet official packages are written in Typescript.

Install my-moodlenet-mjs-pkg-template

Signup using the web-app .

Note: Do not use sensible passwords as the system saves the email-password credentials unencrypted in the database.

Since no SMTP has been configured, the signup confirmation email supposed to be sent will be logged in the terminal:

hey {display name} confirm your email with /.pkg/@moodlenet/simple-email-auth/confirm-email/{LONG_HASH}

Copy the url path (/.pkg/@moodlenet/simple-email-auth/confirm-email/{LONG_HASH}) apply the localhost and paste it to the browser to confirm your email

localhost:8080/.pkg/@moodlenet/simple-email-auth/confirm-email/{LONG_HASH}

You’ll be logged in automatically and will be able to use the chosen credentials to login other times When logged-in, navigate to the settings page in advanced section, where you can enable "dev mode”.

Then proceed to extensions / install extension section and submit the package absolute path to your package local folder.

The system will install the package and restart.

It will take some time to rebuild the web-app to see the results

Questions? Please take a look in the MoodleNet Community and Tracker for answers or to ask for help.

Creating custom MoodleNet packages

A Moodlenet package is a standard ESM package defining a main ESM module.

@moodlenet/core will import it at startup.

// package.json
{
"name”: "my-moodlenet-package,
"version”: "1",
 "type": "module",
"exports": {
  ".": "./src/server/main.mjs"
}
}
Declare dependency

Your MN package must declare its dependency to the @moodlenet/core and other relevant packages package.json.

The core will import the main module at startup. The package "connects” to the core:

// package.json
{
  "peerDependencies”: {
    "@moodlenet/core: "^0.2.0
 }
}

Mono-Repository management with Lerna.js

MoodleNet project takes leverages lerna.js to manage multi-package mono-repository .

Please refer to Lerna documentation to understand how it manages mono-repo and project-packages dependency linking in the development environment.

When you need to add or remove a dependency for your package to some MoodleNet core package you can issue

lerna add -P <needed pkg> <packages/your-pkg-dir>

e.g. lerna add -P @moodlenet/react-app packages/my-moodlenet-mjs-pkg-template

You may also add/remove peerDependencies manually in package.json, in this case remember to execute:

npm run bs

From the root folder to update links to dependent packages.

Extend the web application

Use @moodlenet/react-app "plugin” api, during initialization to extend the web-app with a custom set of components.

import { pkgConnection } from '@moodlenet/core'
import reactApp from '@moodlenet/react-app'
const reactAppPkg = await pkgConnection(import.meta, reactApp)
await reactAppPkg.api('plugin')({
 mainComponentLoc:
    [path, 'to', 'MainComponent.jsx']
})

Define and deploy APIs

Your package will probably need to define and deploy its own APIs.

APIs are simply a collection of async functions - along with a params formal validation function - organized in a structured Js object.

APIs will be registered in the system with a path-like string, having your package name as prefix and apth following api structure.

// src/server/main.mjs
import { connectPkg, defApi } from '@moodlenet/core'
const myApis = {
  hello:{
     world: defApi( ctx => 
        async (p1,p2) => { return // something } , 
       (...params) => { /* … validate params */ }
  )
}
const connection = await connectPkg(import.meta, { 
  apis: myApis 
})
// will register 1 api: 
// my-moodlenet-package/1.0/hello/world

APIs access

Apis can be accessed by any package running in NodeJs processes using specific @moodlenet/core functions pointing to the path of the desired API.

// from within the backend:
// locate an package api by path
import myMNPkgConn from
   ‘my-moodlenet-package’
const myMNPkg = await pkgConnection(import.meta, myMNPkgConn)
const helloWorldApi =
  myMNPkg.api(‘hello/world’)
// call api as an async function
const result = await
  helloWorldApi(helloParam, worldParam)

APIs Primary Adapters

Primary adapters implement API accessibility from external processes using some transport and protocols. Currently MoodleNet provides one Api-primary-adapter to access APIs by HTTP, which is implemented by @moodlenet/http-server. @moodlenet/http-server API HTTP adapter exposes package APIs as HTTP-POST endpoints. That endpoint is a path comprising the package name and the defined API path base, after the base API endpoint ( currently .pkgs ), having a JSON object body representing the api arguments. For example,

.pkgs/my-moodlenet-package/1.0/hello/world

body:

{

 "args” : [

   "hello-param1”,

   "world-param2”

 ]

}

Furthermore, in the web-app, @moodlenet/react-app provides libraries to use a syntax similar to within-backend-access for easy and strongly typed API calls to the server.

APIs Access Control

Packages register apis to @moodlenet/core which mediates api-call requests and responses, performing all fundamental checks and access controls.

  • checks requested pkg version against deployed pkg version for granting compatibility
  • calls api’s params formal validation function before forwarding to actual api function
  • (TBD) checks matching of scopes associated with api and caller (user or package)
  • provides the api a call-context holding an extensible set of metadata (e.g. user session, caller pkg … )
  • (TBD) any package can register for adding context metadata to an api call

APIs Authorization Scopes (TBD)

The core will export functions to define package-specific auth-scopes - similar to OAuth specs.

defApi() will provide options to apply own or other-pkg’s auth-scopes to api.

All Api accesses will be authorized at core level checking scopes assigned to api against scopes assigned to caller. Note that the caller may be a user using some primary adapter e.g. HTTP or can be simply another package, on its behalf, from within the system.

Packages will have to declare which scopes they will need to be granted in order to perform their functionalities.

Package scope-dependencies should be granted by the admin at installation time in order to complete the installation - similar to what happens on smartphones.

Testing MoodleNet packages

Once we’re happy with package development on dev-environment, we can try to install it on a real MoodleNet installation, using the admin UI.

Installation of MoodleNet in a production-like environment is a one liner cmd:

npx install \ @moodlenet/create \ dest/folder

Ensure ArangoDB is running and once inside the "dest/folder" installation directory:

npx @moodlenet/core

Create a user and navigate to the settings page where you can enable "dev mode”. Then proceed to extensions/install section and submit the package absolute path to local folder.

Questions? Please take a look in the MoodleNet Community and Tracker for answers or to ask for help.

Important links