Overview
Fess can display thumbnail images in search results. Thumbnail images are generated based on the MIME Type of search results. For supported MIME Types, thumbnail images are generated when displaying search results. Thumbnail generation processes can be configured and added for each MIME Type.
To enable thumbnail image display, log in as an administrator and enable thumbnail display in the General settings.
Supported File Formats
Image Files
| Format | MIME Type | Description |
|---|---|---|
| JPEG | image/jpeg | Photos, etc. |
| PNG | image/png | Transparent images, etc. |
| GIF | image/gif | Including animated GIFs |
| BMP | image/bmp, image/x-windows-bmp, image/x-ms-bmp | Bitmap images |
| TIFF | image/tiff | High-quality images |
| SVG | image/svg+xml | Vector images |
| Photoshop | image/vnd.adobe.photoshop, image/photoshop, application/x-photoshop, application/photoshop | PSD files |
Document Files
| Format | MIME Type | Description |
|---|---|---|
application/pdf | PDF documents | |
| Word | application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document | Word documents |
| Excel | application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | Excel spreadsheets |
| PowerPoint | application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation | PowerPoint presentations |
| RTF | application/rtf | Rich text |
| PostScript | application/postscript | PostScript files |
HTML Content
| Format | MIME Type | Description |
|---|---|---|
| HTML | text/html | Generates thumbnails from embedded images in HTML pages |
Required External Tools
Thumbnail generation requires the following external tools. Install them according to the file formats you need to support.
Basic Tools (Required)
| Tool | Purpose | Linux (apt) | Mac (Homebrew) |
|---|---|---|---|
| ImageMagick | Image conversion & resize | apt install imagemagick | brew install imagemagick |
Note
Both ImageMagick 6 (convert command) and ImageMagick 7 (magick command) are supported.
SVG Support
| Tool | Purpose | Linux (apt) | Mac (Homebrew) |
|---|---|---|---|
| rsvg-convert | SVG to PNG conversion | apt install librsvg2-bin | brew install librsvg |
PDF Support
| Tool | Purpose | Linux (apt) | Mac (Homebrew) |
|---|---|---|---|
| pdftoppm | PDF to PNG conversion | apt install poppler-utils | brew install poppler |
MS Office Support
| Tool | Purpose | Linux (apt) | Mac (Homebrew) |
|---|---|---|---|
| unoconv | Office to PDF conversion | apt install unoconv | brew install unoconv |
| pdftoppm | PDF to PNG conversion | apt install poppler-utils | brew install poppler |
For Red Hat-based OS, install the following packages:
$ sudo yum install unoconv libreoffice-headless vlgothic-fonts ImageMagick poppler-utils
PostScript Support
| Tool | Purpose | Linux (apt) | Mac (Homebrew) |
|---|---|---|---|
| ps2pdf | PS to PDF conversion | apt install ghostscript | brew install ghostscript |
| pdftoppm | PDF to PNG conversion | apt install poppler-utils | brew install poppler |
HTML File Thumbnail Images
HTML thumbnail images use images specified or included in the HTML. Thumbnails are searched and displayed in the following order:
The content value of a meta tag with name attribute “thumbnail”
The content value of a meta tag with property attribute “og:image”
An appropriately sized image from an img tag
Configuration
Configuration File
The thumbnail generator is configured in fess_thumbnail.xml.
src/main/resources/fess_thumbnail.xml
Main Configuration Items (fess_config.properties)
The following items can be configured in app/WEB-INF/classes/fess_config.properties or /etc/fess/fess_config.properties.
# Minimum width for thumbnail images (pixels)
thumbnail.html.image.min.width=100
# Minimum height for thumbnail images (pixels)
thumbnail.html.image.min.height=100
# Maximum aspect ratio (width:height or height:width)
thumbnail.html.image.max.aspect.ratio=3.0
# Generated thumbnail width
thumbnail.html.image.thumbnail.width=100
# Generated thumbnail height
thumbnail.html.image.thumbnail.height=100
# Output format
thumbnail.html.image.format=png
# XPath to extract images from HTML
thumbnail.html.image.xpath=//IMG
# Excluded extensions
thumbnail.html.image.exclude.extensions=svg,html,css,js
# Thumbnail generation interval (milliseconds)
thumbnail.generator.interval=0
# Command execution timeout (milliseconds)
thumbnail.command.timeout=30000
# Process destroy timeout (milliseconds)
thumbnail.command.destroy.timeout=5000
generate-thumbnail Script
Overview
generate-thumbnail is a shell script that performs actual thumbnail generation. When installed via RPM/Deb packages, it is installed at /usr/share/fess/bin/generate-thumbnail.
Usage
generate-thumbnail <type> <url> <output_file> [mimetype]
Arguments
| Argument | Description | Example |
|---|---|---|
type | File type | image, svg, pdf, msoffice, ps |
url | Input file URL | file:/path/to/file.jpg |
output_file | Output file path | /var/lib/fess/thumbnails/_0/_1/abc.png |
mimetype | MIME type (optional) | image/gif |
Supported Types
| Type | Description | Tools Used |
|---|---|---|
image | Image files | ImageMagick (convert/magick) |
svg | SVG files | rsvg-convert |
pdf | PDF files | pdftoppm + ImageMagick |
msoffice | MS Office files | unoconv + pdftoppm + ImageMagick |
ps | PostScript files | ps2pdf + pdftoppm + ImageMagick |
Examples
# Generate thumbnail for image file
./generate-thumbnail image file:/path/to/image.jpg /tmp/thumbnail.png image/jpeg
# Generate thumbnail for SVG file
./generate-thumbnail svg file:/path/to/image.svg /tmp/thumbnail.png
# Generate thumbnail for PDF file
./generate-thumbnail pdf file:/path/to/document.pdf /tmp/thumbnail.png
# GIF file (specify MIME type to enable format hint)
./generate-thumbnail image file:/path/to/image.gif /tmp/thumbnail.png image/gif
Thumbnail Storage Location
Default Path
${FESS_VAR_PATH}/thumbnails/
or
/var/lib/fess/thumbnails/
Directory Structure
Thumbnails are stored in a hash-based directory structure.
thumbnails/
├── _0/
│ ├── _1/
│ │ ├── _2/
│ │ │ └── _3/
│ │ │ └── abcdef123456.png
│ │ └── ...
│ └── ...
└── ...
Disabling Thumbnail Job
To disable the thumbnail job, configure the following:
In the administration screen under System > General, uncheck “Display Thumbnails” and click the “Update” button.
Set
thumbnail.crawler.enabledtofalseinapp/WEB-INF/classes/fess_config.propertiesor/etc/fess/fess_config.properties.
thumbnail.crawler.enabled=false
Restart the Fess service.
Troubleshooting
Thumbnails Not Being Generated
Check external tools
# Check ImageMagick
which convert || which magick
# Check rsvg-convert (for SVG)
which rsvg-convert
# Check pdftoppm (for PDF)
which pdftoppm
Check logs
${FESS_LOG_PATH}/fess-thumbnail.log
Run script manually
/usr/share/fess/bin/generate-thumbnail image file:/path/to/test.jpg /tmp/test_thumbnail.png image/jpeg
Errors with GIF/TIFF Files
When using ImageMagick 6, specify the MIME type to enable format hints. This is done automatically if Fess is configured correctly.
Error example:
convert-im6.q16: corrupt image `/tmp/thumbnail_xxx' @ error/gif.c/DecodeImage/512
Solutions:
Upgrade to ImageMagick 7
Or verify that MIME type is being passed correctly
SVG Thumbnails Not Being Generated
Check if
rsvg-convertis installed
which rsvg-convert
Test conversion manually
rsvg-convert -w 100 -h 100 --keep-aspect-ratio input.svg -o output.png
Permission Errors
Check permissions on the thumbnail storage directory.
ls -la /var/lib/fess/thumbnails/
Fix permissions if necessary.
chown -R fess:fess /var/lib/fess/thumbnails/
chmod -R 755 /var/lib/fess/thumbnails/
Platform Support
| Platform | Support Status | Notes |
|---|---|---|
| Linux | Fully supported | - |
| macOS | Fully supported | Install external tools via Homebrew |
| Windows | Not supported | Due to bash script dependency |