A service for serving ePub files and related content, including dynamically sized images.
To install the resource server on a host, you need to perform the following steps:
Get a copy of the JAR file that contains the version you want to install, called resource-server-assembly-n.n.n.jar.
Create a configuration file application.conf
which sets the following properties:
- data_dir (REQUIRED): This specifies the root directory that contains the files to be served up by the service.
- cache.directory (REQUIRED): This specifies a directory that will contain a cache of smaller versions of images.
- resource.server.port (REQUIRED): This specifies the port number on which the embedded web server listens.
Additionally, you may want to set the following properties:
- tmp.directory (OPTIONAL): This names the directory that will contain temporary files used internally by the service. If not set, this will default to the system tmp directory.
- threads.count (OPTIONAL): This is the number of threads that will be used for handling image transformation requests (requests for images that specify a specific format, resolution or quality). If not set, this will default to the number of CPUs reported by the JVM on which the service runs.
- cache.threads.count (OPTIONAL): This is the number of threads that will be used for handling background jobs for storing smaller versions of accessed images. If not set, this will default to 0. A value of 0 means that generation of cached images is disabled.
- resource.server.path (REQUIRED): This is the base path of the servlet that handles resource requests. Should be left as "/" in normal cases.
Pre-requisite: Make sure you have sbt and Java 7 installed on your system and on your path.
Copy the config file src/main/resources/resource-server.properties.example to a file called resource-server.properties and override the properties for your local system. In particular, set the 'data_dir' property to point at the root directory to serve up files from.
The run it using the commands:
$ sbt run
Or, for automatic restart on change while developing, use:
$ sbt
> ~re-start
Run the command:
$ sbt assembly
This will build a file resource-server-assembly-n.n.n.jar which contains everything you need to run a server. To run it, first make sure you have a properties file as described above in the same directory as the jar file, then use the command:
$ java -jar resource-server-assembly-n.n.n.jar
You must insure you have libpng and imagemagick installed, then you can follow the usual bundle install and cucumber procedure:
$ brew install libpng imagemagick
$ MOUNT_DIR=<image directory> bundle exec cucumber
NOTE: The image directory given to the Cucumber tests must match the corresponding setting in the application.conf
file used with the service.
The performance tests use Gatling 2, which at the time of writing is not released yet. The latest snapshot can be downloaded from the Sonatype repository. (These tests will not run with Gatling 1)
### Test setup ###
In bin/gatling.sh
(in your Gatling installation), set the following if you have enough memory:
-Xms10G -Xmx10G -Xmn1G
Also, in conf/gatling.conf
, set the following:
percentile1 = 50 # in percent
percentile2 = 90 # in percent
allowPoolingConnection = false # allow pooling HTTP connections (keep-alive header automatically added)
connectionTimeout = 1000 # timeout when establishing a connection
Edit the test properties files for your environment (e.g. to point at the resource server you want to test). These are located in <baldrick home>/performance-tests/images/
.
- Rename the from
*.properties.example
to*.properties
, to create the following files:- ImageScenarios.properties
- ImageSimulations.properties
- Set the resource server document root to point to the
<baldrick root>/performance-test/images/test-files
directory. - Run the script `test-files/duplicate.sh' that copies the big-0000.png and epub files 10,000 times.
To include checking of the content of returned images using MD5 hashes:
- Edit the ImageScenarios.scala to include or exclude the MD5 response size check (this is commented out by default).
The setup above describes how to run the performance tests on a set on well known input files. You can also run some of the tests against an arbitrary set of test files, such as a selection of images and ePub files from the real system. In this case, you have to disable the MD5 checks, and the ePub file tests, as these currently only work with well-known input data.
To run tests from a 'clean' state, that takes into account work done on image background processing:
- Stop the resource server.
- Delete any cached files (in the directory set in the
cache.directory
property in the resource server config. - Start the resource server.
If testing performance of the resource server given an already populated cache of resized images, run the tests to completion first, then restart the test without clearing the cache directory.
Run tests by executing:
<gatling2_home>/bin/gatling.sh -sf <baldrick home>/performance-tests/images/ -s com.blinkboxbooks.resourceserver.ResourceServerSimulation
You can also add an alias into your .profile/.bash_profile if running on Linux or OS/X:
alias grun='<gatling2 home>/bin/gatling.sh'
Or, do environment or PATH variable updates, whatever is easiest.
When the tests have completed, Gatling will generate a report containing the results.