Image Service | Version 4

Image Service Guide

The Image Service provides retrieval, generation and centralized storage of image variants.

Image Store

Image variants are supposed to be saved in an object storage which is compatible to the Amazon AWS S3 API (for example Google Cloud Storage or Amazon S3).

Image Access Service

The Image Access Service is intended to generate, persist and deliver image variants when requested by an image url.
It is recommended to run multiple instances of the Image Access Service to achieve better performance and to relieve Sophora Servers.
An Access Service should either connect to a Sophora Staging Server with to only deliver published images or connect to the Sophora Primary/Replica Server with to deliver the latest (working) version of images which should be used for previews.

Because of possible latency-related synchronization delays between Staging Servers, the Access Service will deliver image variants with a shorter Cache-Control: max-age HTTP header if the requested image is potentially outdated. The long-/short-cache-duration for up-to-date/outdated images can be configured ("Configuration Image Access Service").
For this feature, the Access Service reads image- and image variant related tags which are saved in the image store.

Image Update Service

The Image Update Service performs invalidation of image variants when either image documents or image variant documents have been changed. It can also clean up old data from the S3 storage.
There has to be only one instance connected to the Sophora Primary Server.

When an image document or image variant document has been saved, published, deleted or set offline, corresponding data will be deleted in the image-store and will be regenerated later by the Access Service on demand.
Deleted or offline images/variants will be tagged in the image store.

In case of a downtime or connection loss, potentially missed document changed events will be refetched when the Update Service reconnects to the Sophora Primary Server.

Health Checks

The Health Endpoint /actuator/health extends the Spring default health indicator. If there is no connection to the image store, the Service will be flagged as DOWN.
Internally, the Image Update Service independently checks the connection to the Sophora Primary Server and to the image store to early detect and handle any connection problems.

Security Notes

It is strongly recommended to deploy the Image Access Service with a CDN, because the service itself does not detect and protect against Denial of Service (DoS) attacks.

Best Practices

Multiple webapps with the same Sophora repository

If you have multiple webapps that deliver content from the same Sophora repository, you should only use one image store and one Image Update Service with multiple Image Access Services.


sophora.image-service.url.domain-nameSpecifies the domain for absolute URLs (scheme://host:port").

URL Format

Path to the Access ServiceImage UUIDModification timestampsVariantSlug (optional)Image file format
The uuid of the image documentMinimum required modification dates for the image document/image variant document. Timestamps are base64 encoded and required due to caching and synchronization purposes.
Note that a base64 timestamp has the datatype "long". You can use this converter for manual encoding.
The name of the image variant.
Note: If file format "svg" is requested, the variant must be "original"
Optional slug. This can be named whatever you want.The required image file format.
Supported file formats: jpg, jpeg, png, webp, gif, svg

Using the URL module programmatically

To work with Image Service URLs in your Java code, you should use com.subshell.sophora.imageservice:sophora-image-url. Because this module sets up spring beans, you have let Spring scan com.subshell.sophora.imageservice.url as additional base package.


A word about SIMSI. Internally, we have given the Sophora Image Service the nickname "SIMSI". The name is based on the abbreviation of the project in our project management tool "JIRA". We use "SIMSI" in the logo of the module. If our team or this guide uses "SIMSI" in some places, you know why.

Last modified on 6/21/21

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.