Speed up Nextcloud preview generation with imaginary

For years I have been using the Nextcloud app "Preview Generator" with my Nextcloud instance. However, as my Nextcloud instance grows, I'm noticing more and more that it can be extremely resource hungry and slow.

However, since version 24, Nextcloud now offers the ability to add the "imaginary" application as an external preview provider.
The external implentation makes the app scalable, which also makes it interesting for companies.

The company Nextcloud itself seems to be developing imaginary as part of their all-in-one solution Nextcloud AIO. The implementation documentation is a typical Nextcloud nightmare, so today I'm providing instructions on how to use imaginary on your own Nextcloud instance.

Install imaginary via Docker

Create a new directory and add a docker-compose.yml file:

version: '3.1'
services:

  aio-imaginary:
    image: nextcloud/aio-imaginary:latest
    restart: always
    environment:
      - PORT=9000
    ports:
      - 127.0.0.1:9000:9000
    command: -concurrency 50 -enable-url-source -log-level debug

Start the container via docker compose:

docker compose up -d

Nextcloud configuration

Disable the app "Preview Generator" if installed via the Nextcloud administration interface.

Add imaginary as a PreviewProvider at Nextcloud.

Either via CLI:

php /var/www/html/occ config:system:set enabledPreviewProviders 0 --value="OC\\Preview\\Imaginary"
php /var/www/html/occ config:system:set preview_imaginary_url --value="http://127.0.0.1:9000"

occ command

Or via config.php in your nextcloud folder:

  'enabledPreviewProviders' => 
  array (
    0 => 'OC\\Preview\\Imaginary',
    ... 
   ),
  'preview_imaginary_url' => 'http://127.0.0.1:9000',

config.php

Restart your webserver.

Testing

Imaginary is used only for new images. Although previews can also be generated on-the-fly, this process is much slower. Old images remain untouched until they are called up but there is a trick on how to generate also older preview files (see Rebuild preview files for all images below).

Test if imaginary works

Via CLI:

curl -O "http://127.0.0.1:9001/crop?width=500&height=400&url=https://raw.githubusercontent.com/h2non/imaginary/master/testdata/large.jpg"

The file large.jpg has the pixel dimensions 1920x1080. You should find the same file with the dimensions 500x400 pixels in the folder where you executed the curl command.

Via Web:

Imaginary displays a small WebGUI for experimentation at http://127.0.0.1:9000/form.

Test if nextcloud uses imaginary

Open the docker logs of imaginary:

docker logs -f imaginary-aio-imaginary-1

You should see the following lines for each image you upload from now on:

2022/12/29 15:27:30 FreeOSMemory()
192.168.128.1 - - [29/Dec/2022 15:27:59] "POST /pipeline?operations=%5B%7B%22operation%22%...%7D%5D HTTP/1.1" 200 13914 0.2474
2022/12/29 15:28:00 FreeOSMemory()
192.168.128.1 - - [29/Dec/2022 15:28:10] "POST /pipeline?operations=%5B%7B%....%7D%5D HTTP/1.1" 200 12810 0.1894

imaginary-aio-imaginary-1

Rebuild preview files for all images

Imaginary can also be used to create previews for non-new files. However, the old preview generator must still be active for this.

The slower preview generator is used only for the OCC command to trigger generation. A cronjob is not necessary.

Steps:

Install and activate the Preview Generator:

occ app:install previewgenator
occ app:enable previewgenator

As a precaution, do a rescan of your appdata directory to remove any errors or orphaned files:

occ files:scan-app-data

Now use the Preview Command from the Preview Generator to generate thumbnails of all previews:

occ preview:generate-all --verbose

Nextcloud does not use the Preview Generator to generate the previews, but Imaginary. You should see bunch of queries in the Imaginary logs.

You can deactivate or delete the preview generator after the build:

occ app:remove previewgenerator