@educandu/educandu v3.12.0

educandu

The educandu framework

Prerequisites

• node.js ^18.0.0
• Docker
• optional: globally installed gulp: npm i -g gulp-cli

The output of this repository is an npm package (@educandu/educandu).

Configuration options

How to use

$ yarn add @educandu/educandu

Use it in code as follows:

import educandu from '@educandu/educandu';

educandu({
  appName: 'My educandu app',
  port: 3000,
  mongoConnectionString: 'mongodb://root:rootpw@localhost:27017/dev-educandu-db?replicaSet=educandurs&authSource=admin',
  skipMaintenance: false,
  cdnEndpoint: 'http://localhost:9000',
  cdnRegion: 'eu-central-1',
  cdnAccessKey: 'UVDXF41PYEAX0PXD8826',
  cdnSecretKey: 'SXtajmM3uahrQ1ALECh3Z3iKT76s2s5GBJlbQMZx',
  cdnBucketName: 'dev-educandu-cdn',
  cdnRootUrl: 'http://localhost:9000/dev-educandu-cdn',
  customResolvers: {
    resolveCustomPageTemplate: null,
    resolveCustomHomePageTemplate: null,
    resolveCustomSiteLogo: null,
    resolveCustomPluginInfos: null
  }).required(),
  publicFolders: [{ publicPath: '/', destination: path.resolve(thisDir, '../static') }],
  resources: ['./test-app/resource-overrides.json'].map(x => path.resolve(x)),
  themeFile: path.resolve('./test-app/theme.less'),
  additionalControllers: [MyCustomPageController],
  additionalHeadHtml: '<link rel=\"apple-touch-icon\" sizes=\"180x180\" href=\"/apple-touch-icon.png?v=cakfaagbe\">\n<link rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/favicon-32x32.png?v=cakfaagbe\">',
  sessionSecret: 'd4340515fa834498b3ab1aba1e4d9013',
  sessionCookieDomain: 'localhost',
  sessionCookieName: 'APP_SESSION_ID',
  sessionCookieSecure: false,
  sessionDurationInMinutes: 60,
  consentCookieNamePrefix: 'APP_CONSENT_COOKIE_NAME',
  uploadLiabilityCookieName: 'APP_UPLOAD_LIABILITY_COOKIE_NAME',
  announcementCookieNamePrefix: 'APP_ANNOUNCEMENT_COOKIE_NAME',
  xFrameOptions: 'SAMEORIGIN',
  smtpOptions: 'smtp://localhost:8025/?ignoreTLS=true',
  emailSenderAddress: 'educandu-test-app@test.com',
  initialUser: {
    email: 'test@test.com',
    password: 'test',
    displayName: 'Testibus'
  },
  basicAuthUsers: {
    gatekeeper: 'gatekeeperPassword'
  },
  plugins: ['markdown', 'image', 'table', 'audio', 'video'],
  allowedLicenses: ['CC0-1.0', 'CC-BY-4.0', 'MIT'],
  exposeErrorDetails: true,
  disableScheduling: false,
  ambConfig {
    apiKey: 'C36CAD3A805A11EDA1EB0242AC120002',
    image: './test-app/images/app-logo.png',
    publisher: [
      {
        type: 'Organization',
        name: 'My educandu app'
      }
    ],
    about: [
      {
        id: 'https://w3id.org/kim/hochschulfaechersystematik/n78'
      }
    ]
  },
  samlAuth: {
    decryption: {
      pvk: '<private_key>',
      cert: '<certificate>',
    },
    identityProviders: [
      {
        key: 'panda',
        displayName: 'The Panda University',
        entryPoint: 'https://en.wikipedia.org/wiki/Giant_panda',
        cert: 'nonsense',
        logoUrl: '/images/panda-logo.svg',
        expiryTimeoutInDays: 4 * 30
      }
    ]
  }
});

This should run the entire application and provide you with an admin user as defined on the initialUser setting.

How to override the styles

In order to override the styles provided by educandu you need to import the main.less of the educandu project and override the less variables provided. An example override implementation is provided by the test-app in the main.less file. We will keep this file updated so any user will know what can be overriden. Alternatively you can go to the global-variables.less in educandu and consult the list there.

How to run and develop locally

The gulpfile has a number of useful tasks for local development which can be run with gulp {taskName}, most commonly used:

• (default): build and start up the test app (in watch mode), which is set up to use educandu, CLI args:
  • --instances 3 (number of app instances to run, optional, default 1)
  • --tunnel (flag to run using the tunnel proxy, optional, default: no tunneling)
• test: runs all tests (with coverage)
• testWatch: runs tests in watch mode
• lint: runs eslint
• fix: runs eslint in fixing mode
• up: starts all the containers (if not already running)
• down: stops all the containers and deletes them
• maildev(Up|Down), mongo(Up|Down), minio(Up|Down): starts/stops individual containers
• createSamlCertificate: creates a self-signed certificate that can be used for SAML de/encryption, CLI args:
  • --domain my-domain.com (common name value, mandatory)
  • --days 365 (expiration time, optional, default: 100 * 365)
  • --dir ./output (output directory, optional, default: ./certificates)

By default the test application requires that the following ports are available to be taken:

• 3000: the test application or the load balancerin case of load balancing (instances > 1)
• 400x: the individual test application instances, in case of load balancing (instances > 1)
• 8000: maildev UI, can be used for debugging emails that would be sent to the users (http://localhost:8000)
• 8025: maildev SMTP server
• 9000: minio server and UI (http://localhost:9000)
• 21017: mongodb server

The ports can be changed in gulpfile.js and need to be reflected in test-app/index.js.

When tunneling is enabled, the following environment variables are required to be set:

• TUNNEL_TOKEN token used to verify the tunnel connection
• TUNNEL_WEBSITE_DOMAIN domain of the website served over the tunnel
• TUNNEL_WEBSITE_CDN_DOMAIN domain of the cdn belonging to the website served over the tunnel
• TUNNEL_WEBSITE_SAML_AUTH_DECRYPTION certificate pems for SAML en-/decryption in JSON format ({ "pvk": <private_key>, "cert": <cert> })

OER learning platform for music

Funded by 'Stiftung Innovation in der Hochschullehre'

A Project of the 'Hochschule für Musik und Theater München' (University for Music and Performing Arts)

Project owner: Hochschule für Musik und Theater München\ Project management: Ulrich Kaiser