xelos/xelos-worker repository overview

⁠Worker Container

⁠About this container?

The XELOS worker is a stateless docker container which is used to handle jobs issued by XELOS. The base container consists of a flexible base using a swoole server and api controller. The worker will be called using HTTP calls.

• Image is using OpenSwoole installed on top of base images from php:*-cli
• OpenSwoole Documentation: https://openswoole.com/⁠

⁠Install Guide

XELOS is currently using the LibreOffice-Worker and the Video-Worker as part of the System Worker Library. The following service description within your docker-compose.yml should allow to use the worker services:

⁠Libreoffice Worker

The libreoffice worker is converting office documents to PDF format and allows for easier preview of office documents.

  libreoffice:
    image: xelos/xelos-worker:libreoffice
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "curl","-fk", "https://localhost:9501" ]
      timeout: 20s
      retries: 10
    networks:
      - internal-network

⁠Setup Video Worker

The video worker is using ffmpg to convert videos to mp4 format and can be used to extract thumbnails, subtitles for usage in web environments.

  video:
    image: xelos/xelos-worker:video
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "curl","-fk", "https://localhost:9501" ]
      timeout: 20s
      retries: 10
    networks:
      - internal-network

⁠Setup Image Worker

The image worker is using libvips to convert and resize images.

  image:
    image: xelos/xelos-worker:image
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "curl","-fk", "https://localhost:9501" ]
      timeout: 20s
      retries: 10
    networks:
      - internal-network

⁠Advanced settings, Security Option and Security Context

You can add the following advanced options to your docker-compose.yml to improve security and performance. Please make sure you have enough ram when using tmpfs with video worker. Alternatively you can use a volume or set read_only: false.

  image:
    ...
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    read_only: true
    tmpfs:
      - /tmp
      - /server/certs

It is also advised to run the worker containers in an internal network. Libreoffice could be trying the load external resources if it receives specially prepared documents.

networks:
  internal:
    driver: bridge
    internal: true

⁠How do I get the base container set up within my project?

• Adapt your docker-compose.yml, Docker Swarm or K8S Deployment to include the required worker containers
• The service container is using port 9501 by default

services:
  info:
    image: xelos/xelos-worker:base-alpine
    restart: unless-stopped
    networks:
      - backend

Test Echo service from within XELOS web container

curl -X 'POST' 'http://worker:9501/info/echo' -H 'accept: application/json' -H 'Content-Type: application/json'   -d '{"Hello World"}'

⁠Configuration and environment

Each worker usually comes with predefined settings which are read from the environment. The settings are usually considered suitable for the tasks the worker was designed for. You can however change the settings if you require this.

⁠Client / Composer Dependency

The best way to use and consume the worker service container is by using the respective composer client. The dependency is currently only available from a private composer mirror. Update your composer.json by referencing the mirror:

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://repo.xelos.net/composer/",
            "canonical": false
        }
    ],
    "require": {
        "xelos-worker/php-clients": "*"
    }
}

⁠Example Libreoffice Worker:

<?php
$sourceFile = '/tmp/myWord.docx';
$targetFile = '/tmp/myWordAsPDF.pdf';
(new \XELOSWorker\Client\Libreoffice('https://libreoffice:9501'))->convert($sourceFile, $targetFile);

⁠Example Video Worker:

<?php
$pathToVideoFile = '/tmp/myVideo.mov';
$pathToConvertedVideoFile = '/tmp/myVideo.mp4';
try {
    $videoWorker = (new \XELOSWorker\Client\Video('https://video:9501'));
    // Optional: Check supported formats 
    // $videoWorker->getSupportedFileExtensions();
    
    // Step 1: Upload Video to worker
    $fileInfo = $videoWorker->uploadVideoFile($pathToVideoFile);
    
    // Step 2: Generate preview thumbnails
    $previewImages = $videoWorker->generatePreviewImages();
    foreach ($previewImages as $previewImage) {
        $thumbCount = \basename(\substr($previewImage['downloadFileId'], \strpos($previewImage['downloadFileId'], ':')+1));
        $saveTargetFile = $destinationFolder.$thumbCount;
        $videoWorker->downloadFile($saveTargetFile, $previewImage['downloadFileId']);
    }
    
    // Step 3: Encode Video to specific quality
    $videoWorker->encodeVideo($quality = 'sd');
    
    // Step 4: Download encoded Video from worker
    $videoWorker->downloadFile($pathToConvertedVideoFile, $fileInfo['fileId'].':sd');
    
} catch(Exception $exception){
    // Handle error
}

⁠Example Image Worker:

<?php
$pathToPDF = '/tmp/myWordAsPDF.pdf';
$imgFile = '/tmp/preview.png';
$resizedImgFile = '/tmp/preview-resized.png';
try {
    $imageWorker = (new \XELOSWorker\Client\Image('https://image:9501'));
    $imageWorker->pdfToImage($pathToPDF, $imgFile, $page = 0, $dpi = 300);
    $imageWorker->thumbnail($imgFile, $resizedImgFile, $width = 800, $height = 600, $crop = true);
} catch (Exception $exception) {
    //Handle error
}

⁠Using TLS / HTTPS

The container will create a selfsigned certificate on first startup and check for the public/private certificates at the following locations if not specified otherwise as ENV variables:

• /server/certs/ssl.crt
• /server/certs/ssl.key

Please consult OpenSwoole documentation for further information about the TLS implementation: https://openswoole.com/docs/common-questions/enable-tls-https⁠

⁠How do I set up my DEV environment to contribute code?

Mount code from this repository locally:

services:
  worker:
    image: xelos/xelos-worker:base-alpine
    restart: unless-stopped
    ports:
      - 9501:9501
    volumes:
      - ../xelos-worker:/server/xelos-worker
    networks:
      - backend

⁠Misc internals

The following information can be useful if you are planning on rebuilding or combining worker containers:

• The current default entrypoint is php /server/xelos-worker/startup.php
• The default command will run a single service, e.g.: CMD ["--service=libreoffice"]
• You could combine multiple services in to a single container e.g.: CMD ["--service=libreoffice,video"] or even omit the --service argument and run all available services.
• You can start a service in debug mode to prevent an early exit, e.g.: CMD ["--service=libreoffice","--dev-mode=true"]
• The default uid is 10000 (worker) in gid 10000 (worker)

You can also use the provided docker/docker-compose.yml to startup the services for a quick test.

⁠Who do I talk to?

• BLUEEND / Stefan