Sophora Image Service: Installation & Configuration

Installation

For running Access Service and Update Service in a cloud environment, we provide docker images and helm charts on our docker registry.
Be sure to mount your specific application.yml, (if desired also logback-spring.xml) into the containers at /app/config.

If you would not like to use docker, locate your configuration files next to the jar-file. A rudimentary startup command for Access- and Update Service could look as follows:

 java -jar sophora-image-access-service-4.x.x.jar
 java -jar sophora-image-update-service-4.x.x.jar

Configuration

Sophora Image Access- and Update Services are Spring Boot applications and is therefore configurable by using an application.yml file or through matching environment variables.

Configuration Image Update Service & Image Access Service

Image Access Service and Image Update Service have following configuration properties in common, hence they are documented once here. See also component-specific configuration below.

Property	Description	Default
`spring.profiles.active`	The active spring profile has an influence on the default logging behavior. With "prod" active, logs are printed with JSON-format.	prod
`server.port`	Server port of the application
`endpoints.web.exposure.include`	Default Spring and custom endpoints that will be available to check certain application metrics under /actuator.	sophoraserver, info, health, jolokia, threaddump, prometheus
`sophora.image-service.s3-image-store.host`	The host URL of the image store, i.e. https://storage.googleapis.com
`sophora.image-service.s3-image-store.access-key-id`	AccessKeyId for accessing the storage bucket
`sophora.image-service.s3-image-store.secret-access-key`	SecretAccessKey for accessing the storage bucket
`sophora.image-service.s3-image-store.bucket-name`	The storage bucket name
`sophora.image-service.s3-image-store.create-bucket`	This property should always be `false` in production. It can be helpful to automatically create a non-existent bucket during development.	false
`sophora.client.server-connection.urls`	The Sophora Servers to connect with. The Update Service should connect to the Primary Server, Acces Services (except for preview) should connect to Replica Servers.
`sophora.client.server-connection.username`	Username for Client connection to the Sophora Server
`sophora.client.server-connection.password`	Password for Client connection to the Sophora Server

Configuration Image Access Service

Property	Description	Example	Default
`sophora.image-service.image-access-service.live-mode`	Whether to deliver either only pulished images or only working version images	true/false
`sophora.image-service.image-access-service.lock-cache-cleanup-interval`			5s
`sophora.image-service.image-access-service.long-cache-duration`	Cache duration for stable images (in contrast to short-cache-duration)	1d (1 day)
`sophora.image-service.image-access-service.short-cache-duration`	Cache duration for instable images that might not be up to date at request time due to replication latency	1m (1 minute)
`sophora.image-service.image-access-service.image-generation-warning-threshold`	Threshold (in ms) for normally expected image binary data generation. When generation time exceeds this value, a log message with image details and generation time will be logged with level `WARN`. Otherwise, the loglevel for this message is `DEBUG`	1000	1500
`sophora.image-service.image-access-service.scaling.enabled`	Whether the access service should allow the parameters `width` or `height` for dynamic scaling of images.	true/false	false
`sophora.image-service.image-access-service.scaling.allowed-heights`	Configuration for heights allowed for scaled images, if the requested `height` is not configured, no image will be created. If configured, all values have to be in the range from 1 to 10.000. If empty, height scaling is effectively disabled. If set to `null`, all image heights are allowed.	[100, 200, 1024]	null
`sophora.image-service.image-access-service.scaling.allowed-widths`	Configuration for widths allowed for scaled images, if a requested `width` is not configured, no image will be created. If configured, all values have to be in the range from 1 to 10.000. If empty, width scaling is effectively disabled. If set to `null`, all image widths are allowed.	[75, 150, 768]	null
`sophora.image-service.image-access-service.generation.metadata.remove-all`	Determines how EXIF and IPTC metadata from uploaded/imported binary data is handled true: existing EXIF/IPTC metadata will be removed false: existing EXIF/IPTC metadata is preserved unset: existing EXIF/IPTC metadata is preserved, when neither `iptc` nor `exif` is set This value can only be set if properties `iptc` and `exif` are not set, otherwise the configuration is considered invalid!	true/false	unset
`sophora.image-service.image-access-service.generation.metadata.iptc`	List of IPTC-IIM tag names that should be written into delivered image variants, only supported tag names are allowed. For more information about IPTC-IIM, visit the Wikipedia page. A complete list with all supported tag names and their IPTC-Code can be found in Appendix A. If this property is empty, but metadata handling is enabled (i.e. `remove-all` is true or `exif` is set), delivered image variants will have no IPTC-IIM metadata.	- Credit - City	unset
`sophora.image-service.image-access-service.generation.metadata.exif`	List of EXIF tag names that should be written into delivered image variants, only supported tag names are allowed. For more information about Exif tags, visit the Wikipedia page. A complete list with all supported tag names and their ID can be found at the Appendix B. If this property is empty, but metadata handling is enabled (i.e. `remove-all` is true or `iptc` is set), delivered image variants will have no EXIF metadata.	- Copyright	unset

Configuration Image Update Service

Property	Description	Default
`sophora.image-service.image-event-listener.ping-event`	The duration after which a synthetic ping event is queued if no image-related event occurred during this time. This lets the Update Service know since when it could have missed any events that should be reconsidered in case of downtime.	30s
`sophora.image-service.image-event-worker.max-retries`	In case of a failure on image event handling, this value declares the max. number of retries that should be performed. If value is 0, no retry will occur at all.	3
`sophora.image-service.image-event-worker.thread-count`	The number of threads to be used for handling image-related events.	2
`sophora.image-service.image-event-worker.retry-delays-ms`	A list of delays for image event retry process. In default, the first retry will be after 1000ms, the second retry after 2500ms, every next retry 6000ms	1000, 2500, 6000
`sophora.image-service.image-event-worker.connection-test-retry-interval`	The duration to wait between connection checks if either the Sophora Server or the image store cannot be reached.	10s
`sophora.image-service.image-event-worker.update-last-processed-timestamp-grace-period`	Grace period before a new lastProcessedTimestamp is persisted in the cloud storage.	10s
`sophora.image-service.cleanup.cron-trigger-expression`	The Cron expression for the interval when the Update Service should check for old data. The special value `"-"` indicates that no cleanup shall be performed.	`0 0 0 * * ?` (every day at 00:00:00)
`sophora.image-service.cleanup.minimum-age-days`	The minimum age of the data in days before it will be removed from the S3 storage.	30

Image Service URL builder

A simple way to create URLs for delivering images and other Sophora documents is the usage of the Sophora URL Library.

If you want to use additional image URL features (e.g. image width or height), you should use the ImageUrlBuilder from the Sophora Image Service. For a working example we assume that you are using the Spring Boot framework for your application. Please ask for support if you need assistance for a different setup.

To create Sophora Image Service URLs in your Spring Boot application, you need at least the following three dependencies. If you use the Sophora URL Library for other URLs, the dependencies are already in your classpath:

[...]
<dependency>
	<groupId>com.subshell.sophora</groupId>
	<artifactId>spring-boot-sophora-commons</artifactId>
	<version>4.x.x</version>
</dependency>

<dependency>
	<groupId>com.subshell.sophora</groupId>
	<artifactId>com.subshell.sophora.api</artifactId>
	<version>4.x.x</version>
</dependency>

<dependency>
	<groupId>com.subshell.sophora.imageservice</groupId>
	<artifactId>sophora-image-url-client</artifactId>
	<version>4.x.x</version>
</dependency>
[...]

You also have to setup the classpath scanning of your application to additionally include the two packages com.subshell.sophora.springbootsophoracommons and com.subshell.imageurlbuilder:

@SpringBootApplication(scanBasePackages = {"com.subshell.sophora.springbootsophoracommons", "com.subshell.imageurlbuilder", "<your-application-package>"})
public class Application {

	public static void main(String[] args) {
		new SpringApplicationBuilder(Application.class)
				.run(args);
	}

}

Finally, you need to setup the Sophora Server connection for the Sophora client and the configuration for the Sophora Image Service URL Builder. For a minimal setup, add the following properties to the application.yml file. A comprehensive description for all configuration properties can be found in the URL configuration section of the Sophora URL Library documentation.

sophora:
  client:
    server-connection:
      username: "<user>"
      password: "<pwd>"
      urls: ["<sophora-server-url>"]

      
  image-service:
    url:
      default-domain: "https://<your-image-service>"

Now you can use Spring's dependency injection to get a configured ImageUrlBuilderProvider.
The following class:

@Component
public class CreateUrls {

	private static final Logger LOG = LoggerFactory.getLogger(CreateUrls.class);
	private final ImageUrlBuilderProvider builderProvider;

	public CreateUrls(ImageUrlBuilderProvider builderProvider) {
		this.builderProvider = builderProvider;
	}

	@PostConstruct
	void init() {
		UUID uuid = UUID.fromString("<image-uuid>");
		String url = builderProvider.forUuid(uuid)
				.build()
				.orElse(null);
		LOG.info("Image url: {}", url);
	}

}

will create this url:

12:37:30.185 INFO -  CreateUrls.init(CreateUrls.java:26) - Image url: https://<your-image-service>/image/<image-uuid>/AAABiNlHWSg/AAABiQIJgMc/original.jpg

The ImageUrlBuilder generated by the ImageUrlBuilderProvider also assists to use other features of the Sophora Image Service. The following code creates a URL with an overlay, image format webp and a specific width:

 UUID uuid = UUID.fromString("<image-uuid>"); 
 String url = builderProvider.forUuid(uuid) 
 .withSlug("interesting-image")
 .withSuffix("webp")
 .withOverlayImage("overlay-image-external-id")
 .withVariantName("16x9")
 .withWidth(1280)
 .build()
 .orElse(null);

The created URL will look like this:

https://<your-image-service>/image/<image-uuid>/AAAAAEmWAtI/AAAAAAAAMDk/16x9/interesting-image.webp?overlay=<overlay-uuid>&overlayModificationDate=AAAAAAA3D3C&width=1280

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

Installation & Configuration