Note:

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

MoodleNet

From MoodleDocs

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 have some courses on Moodle Academy. Both are a bit old but will be updated soon.

Checkout issues and releases on https://github.com/moodle/moodlenet

Current status

We have just released MoodleNet 4.0.0. You can follow the releases on Moodle's Jira tracker at MDLNET.

Roadmap

See our work on new features in the tracker.

Quick start guide

System Requirements

MoodleNet currently runs on

MoodleNet supports these specific versions only, previous version are not supported

The system also needs a reachable instance of ArangoDB v3.10 for data storage

[Note]: prior to version 4.2.1, MoodleNet supported nodejs@v16 and npm@v8

Deploy an ArangoDB instance

MoodleNet uses ArangoDB as main database

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 run ArangDB locally as a service is by using Docker[1] 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|directory for data or setting a password

Install MoodleNet

Install Moodlenet by simply issuing the following npm command

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

That will install all MoodleNet core packages in the chosen 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.

Here's how the default config looks like after install:

{
  "pkgs": {
    "@moodlenet/core": {
      "baseFsFolder": "/path/to/installation/dir/fs",
      "instanceDomain": "http://localhost:8080",
      "npmRegistry": "https://registry.npmjs.org",
      "mainLogger": {
        "consoleLevel": "info",
        "file": {
          "path": "./log/moodlenet.%DATE%.log",
          "level": "info"
        }
      }
    },
    "@moodlenet/crypto": {
      "keys": {
        "alg": "RS256",
        "type": "PKCS8",
        "private": "/path/to/installation/dir/default.crypto.privateKey",
        "public": "/path/to/installation/dir/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": "eqhb30x9iq5"
    },
    "@moodlenet/react-app": {
      "defaultImageUploadMaxSize": "1MB"
    }
  }

Here are 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 (better absolute path instead of relative to MoodleNet process cwd) to the system root folder for system filesystem persistency, if you want to change the system-filesystem-root after the system already run, move or clone the existing folder somewhere else and set this config properly to point to the new path
  • @moodlenet/core.instanceDomain : the public domain of your moodlenet instance (e.g. https://moodlenet.example.com) - the default one (http://localhost:8080) is ok for testing and dev
  • @moodlenet/email-service.nodemailerTransport : the nodemailer transport configuration for the system email service. It can be a simple smtp url string, or a nodemailer standard config object. Notice: with the default configuration { "jsonTransport": true } the system won't send any email, it will simply log them)
  • @moodlenet/system-entities.rootPassword : a static root password for edge cases - you'll use it to give the first admin permission to a user (see below) - this property is optional, if not set the root user is disabled
  • @moodlenet/http-server.port : the HTTP server port to listen

Moodlenet's HTTP service doesn't support HTTPS.

It's always a good practice to back Moodlenet with a HTTP reverse proxy (e.g. nginx, Apache) and it is a must if you want to publish over HTTPS, configuring TLS on it.

Default authentication system

Moodlenet comes with a simple email+password authentication system (pkg @moodlenet/simple-email-auth) that lets users signup and login with a verified email

Users can sign up with their email, receive in their inbox a confirmation link to click and create their user-account

Assign admin privileges to your user

As you deploy a new instance, no user is present in the system.

Signup with your email and create your user.

Test login, then logout and browse to the hidden page http://localhost:8080/login/root, here you can type in the rootPassword (specified in config file) to login as root.

Open the avatar menu on top right header, and click admin link

Click on Users section on the left, and see your user listed there. Activate the admin icon to give yourself admin privileges

Now you can log out and login back with your email, see you gained the admin link in your avatar menu

Admins can directly use that admin page feature anytime to assign and remove admin privileges to other users

Update the system

You can easily upgrade MoodleNet keeping system packages always up-to-date with the minor and patch releases by issuing the command

npm update

from within the installation directory, the same where you start the system

Since MoodleNet is npm-package based, it leverages all npm features for upgrades and new packages installation

Note:

npm update does not upgrade packages for breaking-change versions (major versions, or minor versions for 0.x.y versions, as from node-semver specs)

In case you need to upgrade MoodleNet system packages to newer major versions you may want to either edit manually the main package.json

Or, better, use the utility npm-check-updates:

# for a dry run:
npx npm-check-updates

# to update all packages writing newest version refs in package.json:
npx npm-check-updates -u
npm update

Migrate from V2

If you have a v2 running and want to migrate it to v3 , you can use the @moodlenet/v2-migrate-v3

The v3 system must have access to Moodlenet-V2 persistencies:

V2 persistencies will be used in read-only

Note: in case you use the docker setup as proposed above and have it all running at one server, you need to have two Arango DB instances running at the same time. So just forward a different port (here we use localhost:8530 to access the new Arango db instance):

CONTAINER ID   IMAGE          COMMAND                  CREATED        STATUS        PORTS                       NAME
xxxxxx         arangodb       "/entrypoint.sh aran…"   28 hours ago   Up 28 hours   127.0.0.1:8530->8529/tcp    arangodb-new
yyyyyy         arangodb       "/entrypoint.sh aran…"   4 days ago     Up 28 hours   127.0.0.1:8529->8529/tcp    mn-arangodb

Edit the default.config.json adding a @moodlenet/v2-migrate-v3 section beside the others, it should look like that:

    "@moodlenet/v2-migrate-v3": {
      "v2DbConnectionCfg": {
        "url": "http://your-mn-v2-arangodb-host:8529"
      },
      "v2AssetFolder": "/path/to/v2/asset/folder"
    }

Note that you may also have to adjust the database configuration above for the v3 instance.

After Moodlenet v3 is installed (as above but choosing the early 3.0 version npm create @moodlenet@3.0 – caution: @3.0.0 wouldn't work!), issue the following command from the installation folder:

npm install @moodlenet/v2-migrate-v3@0.5.1

Then just (re)start your v3 instance by running "npm start", the migration will be done, services will be restarted and you can log in.

After migration completed this package can be safely uninstalled.

MoodleNet architecture

MoodleNet is a full stack TypeScript/JavaScript system using:

  • NodeJs
    • NPM Packages [2]
    • ESM Modules [3]
  • Browsers

MoodleNet development environment

Setup development environment

From the command line interface (CLI):

Ensure ArangoDB is running on localhost. You may run it in a Docker container issuing a command as below:

docker run -e ARANGO_NO_AUTH=1 -p 8529:8529 --name=mn3-dev arangodb:3.10

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 initialise the project:

npm install

Copy assets

npx lerna run copy-assets

Install a development server:

npm run dev-install-backend my-dev # <- my-dev: an arbitrary dev-installation name

In the example we chose my-dev as installation name, the tool will then setup a dev installation in ./.dev-machines/my-dev

You can create as many dev installations as you wish.

Run development backend:

npm run dev-start-backend my-dev # <- my-dev : the name you chose when installed

The first run of the system may take some time to install.

The default configuration for dev includes the config @moodlenet/react-app.noWebappServer: true that prevents the server to expensively build and serve the webapp,

so you'll get all backend services served on http://localhost:8080, except for the webapp.

Instead, you'll want to run a webpack+HMR serving the webapp issuing

npm run dev-start-webapp my-dev # <- my-dev: the installation server to point to

Once all started, browse http://localhost:3000, any edits to webapp related code will be Hot-Module-Replaced

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.

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