Skip to main content

Hosting

There are two approaches to hosting itself: Docker (recommended) and an installation on the operating system (Linux is recommended here). Both approaches are described below:

This approach describes hosting the middleware via Docker. This is the generally recommended way, as it can solve some OS specific problems. We describe here the simplest way by using a docker-compose.yml file. For a real productive use we recommend kubernetes or other container ochistration software.

Prerequirements​

  • Docker
  • docker-compose

Configuration​

For the configuration of the service the docker-compose.yml is used. With the Docker version of the middleware, a pre-configured xemiddleware.config.mjs is already shipped. This can either be completely overwritten by mounting the file in the container via a volume or configured via the existing variables.

version: '3'
services:
    middleware:
        image: 'hub.xeditor.com/middleware:latest'
        ports:
            - '8080:8080'
        environment:
            # Variables with default value:
            XEDITOR_MIDDLEWARE_CONFIG: '/usr/app/xemiddleware.config.mjs'
            XEDITOR_MIDDLEWARE_PROTOCOL: 'HTTP'
            XEDITOR_MIDDLEWARE_HTTPS_CA: ''
            XEDITOR_MIDDLEWARE_HTTPS_KEY: ''
            XEDITOR_MIDDLEWARE_HTTPS_CERT: ''
            XEDITOR_MIDDLEWARE_HOST: '0.0.0.0'
            XEDITOR_MIDDLEWARE_PORT: 8080
            XEDITOR_SERVER_URL: 'http://localhost:8080'
            XEDITOR_SERVER_HOST: ''
            XEDITOR_SERVER_PORT: ''
            XEDITOR_SERVER_PROTOCOL: 'HTTP'
            XEDITOR_SERVER_PATH: ''
            XEDITOR_SERVER_ALLOW_UNTRUSTED: 'false'
            XEDITOR_SERVER_CONTENT_TYPE: 'application/x-www-form-urlencoded'
            XEDITOR_MIDDLEWARE_ENABLE_VALIDATE_ON_LOAD: 'false'
            XEDITOR_MIDDLEWARE_ENABLE_COMPRESSION: 'true'
            XEDITOR_MIDDLEWARE_ENABLE_DOCUMENTATION: 'false'
            XEDITOR_MIDDLEWARE_ENABLE_REMOVE_DEFAULT_NAMESPACE: 'false'
            XEDITOR_MIDDLEWARE_MATHML_PROCESSOR: 'xformula'
            XEDITOR_MIDDLEWARE_ENABLE_SVG_SUPPORT: 'false'
            XEDITOR_SPELLCHECKER_URL: ''
            XEDITOR_SPELLCHECKER_HOST: ''
            XEDITOR_SPELLCHECKER_PORT: ''
            XEDITOR_SPELLCHECKER_PROTOCOL: ''
            XEDITOR_SPELLCHECKER_PATH: ''
            XEDITOR_SPELLCHECKER_ALLOW_UNTRUSTED: 'false'
            XEDITOR_SPELLCHECKER_CONTENT_TYPE: 'application/x-www-form-urlencoded'
            XEDITOR_MIDDLEWARE_LOG_LEVEL: 'info'
            XEDITOR_MIDDLEWARE_LOG_OUTPUT_CONSOLE: 'true'
            XEDITOR_MIDDLEWARE_LOG_OUTPUT_FILE: ''
            XEDITOR_MIDDLEWARE_LOG_OUTPUT_RFS_FILE: '/usr/app/logs/middleware.log'
            XEDITOR_MIDDLEWARE_LOG_OUTPUT_RFS_SIZE: '1M'
            XEDITOR_MIDDLEWARE_LOG_OUTPUT_RFS_MAX_FILES: '14'
            XEDITOR_MIDDLEWARE_LOG_OUTPUT_RFS_INTERVAL: '1d'
            XEDITOR_MIDDLEWARE_LOG_OUTPUT_RFS_COMPRESS: 'true'
            XEDITOR_MIDDLEWARE_SCHEMA_CONFIGURATION_FILE: '/usr/app/config/xemiddleware.schema.config.mjs'
            XEDITOR_MIDDLEWARE_HOOK_CONFIGURATION_FILE: '/usr/app/config/xemiddleware.hook.config.mjs'
        # Add path to local xemiddleware.schema.config.mjs / xemiddleware.hook.config.mjs
        volumes:
            - "./config:/usr/app/config"

In addition, at least the file config/xemiddleware.schema.config.mjs and the XSD/XSLT are required here, which can be mounted via the volume.

export const configuration =  {
  'default': 'demo@0.0',
  'demo@0.0': {
    file: './xsd/content.xsd',
    map: {
      'mathml/mathml3.xsd': './xsd/mathml/mathml3.xsd',
      'mathml3-common.xsd': './xsd/mathml/mathml3-common.xsd',
      'mathml3-content.xsd': './xsd/mathml/mathml3-content.xsd',
      'mathml3-presentation.xsd': './xsd/mathml/mathml3-presentation.xsd',
      'mathml3-strict-content.xsd': './xsd/mathml/mathml3-strict-content.xsd',
      'svg/svg.xsd': './xsd/svg/svg.xsd',
      '../modules/xlink.xsd': './xsd/modules/xlink.xsd',
      '../modules/xml.xsd': './xsd/modules/xml.xsd',
    },
    transformation: {
      contenttoeditor: "./xsl/xml-to-html-override.xsl",
      editortocontent: "./xsl/html-to-xml.xsl",
      pastetoeditorfirst: "./xsl/pastetoeditorfirst.xsl",
      pastetoeditorsecond: "./xsl/pastetoeditorsecond.xsl"
    }
  }
}

Now that we have created our docker-compose.yml and config/xemiddleware.schema.config.mjs and placed our XSD/XSLT files in the config folder, we can start the middleware. This can be done easily with the docker-compose up command.

Build your own Docker image​

If there is a possibility to create Docker images in a pipeline and store them in a private repository, then we recommend to create your own Dockerfile. For this you can simply inherit from the base and overwrite all necessary ENV variables and copy all necessary files into the image.

This could look as simple as the following:

FROM hub.xeditor.com/middleware:latest

COPY ./config /usr/app/config

Linux / Operating System​

In this approach, the middleware is installed directly on an operating system.

Prerequirements​

  • NodeJS 18.16.0 (latest LTS)
  • NPM 9.5.1 (Usually comes along automatically with NodeJS.)
  • Java JRE >= 11
  • xsltproc

Installation​

For the installation of the middleware we recommend to create a separate folder on the server e.g. /opt/xeditor/middleware. In the folder we now create a package.json file which takes care of the version of the productive middleware:

{
  "name": "xeditor-middleware-configuration",
  "version": "1.0.0",
  "scripts": {
    "start": "xemiddleware --config ./xemiddleware.config.mjs"
  },
  "dependencies": {
    "@xeditor/middleware": "3.0.0"
  }
}

After that we can already install all needed Node Modules via npm install. Now the middleware can be started and used with the command npm start.

Service​

Linux​

For productive use it makes sense to run the middleware as a service. For this purpose, a /etc/systemd/system/middleware.service file can simply be created.

[Unit]
Description=Xeditor middleware service
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=5
User=centos
WorkingDirectory=/opt/xeditor/middleware
ExecStart=/usr/bin/env node /opt/xeditor/middleware/node_modules/.bin/xemiddleware --config ./xemiddleware.config.mjs

[Install]
WantedBy=multi-user.target

Windows​

In order to use a service on Windows, we use the NodeJS library node-windows. For this we need to install the node-windows dependency:

npm install -S node-windows

After that, we can create a new file here in the project with the name install_service.js in the root of our project:

var Service = require('node-windows').Service;

const path = require('path');
const fs = require('fs');

const logPath = path.join(__dirname, 'logs')
if (!fs.existsSync(logPath)) {
  fs.mkdirSync(logPath)
}

var svc = new Service({
  name:'Xeditor Middleware Serivce',
  description: 'Xeditor Middleware Serivce',
  script: path.join(__dirname, 'node_modules/@xeditor/middleware/bin/xemiddleware.js'),
  scriptOptions: [
    `"--config=xemiddleware.config.mjs"`
  ],
  logpath: logPath
});

svc.on('install',function(){
    console.log("Install complete. Starting...")
    svc.start();
});

svc.on('alreadyinstalled',function(){
    svc.uninstall();
    console.log("Uninstall complete.")
});

svc.install()

To install the service, you can run node install_service.js. Run it again to uninstall the service.