An implementaion of the schul-cloud preview generator service.

The preview generator service creates preview images from downloadable files by using the previewgenerator library.

The preview generator service provides an http(s) endpoint to process incoming requests:

POST /generatepreview
{
    "download_url": "http://example.com/static/powerpoint1.ppt",
    "signed_s3_url": "https://example.com/powerpoint1.jpg?options...",
    "callback_url": "http://example.com/callback/powerpoint1.ppt",
    "options": {
        "width": 200
    }
}

The payload has to be valid JSON, the URL parts are mandatory and the options are optional. The options can be:

• width, height: integer (pixel)
• page: integer (default 1)

And here comes a magic: The generator has internally a default of 256px for both width and height. The generator scales up the preview images until the first value - whether height or width - is reached. So, if you want a 200px wide image and specify only the width of 200px, then an image is created with 181px width and 256px height. To still get a 200px wide image, an oversized height must be specified, e.g. 2000px.

Upon this request, the preview generator service creates an internal generate-preview-job and returns HTTP/1.1 202 Accepted The generate-preview-job consists of the tasks:

1. Download the file The files type is detected by the content-type header field
2. Create the preview image
3. PUT request to the signed_s3_url More information to presigned url you can find on AWS.
4. Reports the success/error to the callback_url:

   • The success report to the callback_url is a request:

     PUT <callback_url>
     {'previewUrl': 'https://example.com/powerpoint1.png'}
     

     The previewUrl is taken from the signed_s3_url path part.

   • The error report to the callback_url is a request:

     PUT <callback_url>
     status: 500 Internal Server Error
     {'error': '<errormessage>'}
     

The preview generator service is protected by BasicAuth authentification strategy. For this, an AUTH_USERPW has to be provided as environment variables at startup (f.e. export AUTH_USERPW=schulcloud:veryStrongPassword).

The supported file-types are: document-formats There are more supported file-types (f.e. .doc), not all types are listed. Furthermore, the preview generator service supports Apple iWorks files. Tese files are zip files, which contains prerendered preview.jpg pictures.

Since the preview generator service uses a job queue, a rabbitmq-server is necessary. For this, at least the AMQP_URL has to be provided as environment variables at startup. F.e. export AMQP_URL: amqp://username:password@rabbitmq/previewgenerator

To get the preview generator service running in a Vagrant VM:

1. Create the folder ./secrets
2. Copy ./resources/rabbitmq-definitions.template.json to ./secrets/rabbitmq-definitions.json. Adjust the amqp <user> and the <sha256-hash-of-users-password>. To get the <sha256-hash-of-users-password> you can follow the (missleading) documentation from rabbitmq: https://www.rabbitmq.com/passwords.html#computing-password-hash. Or you can use my tool. Change to ./resources and run python encrypt_rabbitmq_password.py --password="<your-rabbit-password>" (only python2).
3. The config.yml is already part of the service, but the amqp and webserver credentials must be overwritten. You can do this in the resources/*.servicefiles. Add to the service section: Environment=AMQP_URL=amqp://user:password@localhost/previewgenerator and Environment=AUTH_USERPW=user:password
4. Run vagrant up

Two docker images are created based on the node:10.5.0-stretch Debian-Stretch image.

• docker pull schulcloud/previewgenerator:latest
• docker pull schulcloud/previewgenerator.webserver:latest

So that the previewgenerator-service, previewgenerator-webserver and the rabbitmq-server can be run and connected, docker-compose can be used. For more details see docker-compose.yml. In production mode, however, this file must be adjusted accordingly.

You have to adjust the AUTH_USERPW.

If you don't use an external rabbitmq-server, you have to:

1. Create the folder ./secrets
2. Copy ./resources/rabbitmq-definitions.template.json to ./secrets/rabbitmq-definitions.json. Adjust the amqp <user> and the <sha256-hash-of-users-password>. To get the <sha256-hash-of-users-password> you can follow the (missleading) documentation from rabbitmq: https://www.rabbitmq.com/passwords.html#computing-password-hash. Or you can use my tool. Change to ./resources and run python2 encrypt_rabbitmq_password.py --password="<your-rabbit-password>" (only python2).
3. Adjust the AMQP_URL according to the new credentials.