What Is Shrimp?

Shrimp is a small HTTP-server that provides shrunk images generated from a specified set. It also supports conversion of an image into a different format (jpg, png, gif, webp and heic are supported).

Basic idea

Suppose you want your server to serve resized images over HTTP. You receive a request and use its path to determine source image and use request query string to determine resize parameters for it. So you end up with the following form requests to your server:

  • http://myserver/path/to/image/img.jpg?op=resize&height=128
  • http://myserver/path/to/image/img.jpg?op=resize&width=2500
  • http://myserver/path/to/image/img.jpg?op=resize&max=1024

You can also request a conversion to different format:

  • http://myserver/path/to/image/img.jpg?op=resize&height=128&target-format=png
  • http://myserver/path/to/image/img.jpg?target-format=webp

And that is what Shrimp is about.

Obtain and build


Shrimp is developed under Ubuntu (16.04/18.04) using gcc-8.1 or gcc-7.3.

Shrimp uses ImageMagick for working with images. ImageMagick and all its dependencies (like libjpeg-dev, libpng-dev, libwebp, x265, libde265, libheif and so on) must be installed manually.

All other Shrimp's dependencies come with Shrimp.

Obtain Shrimp sources

Obtain from repository

Just use hg clone command to download Shrimp sources.

hg clone

You can also download a specific Shrimp's version from a Downloads section.


There are two approaches for building Shrimp:

  • by using Docker;
  • by using Mxx_ru.

The simplest one is Docker-build because all necessary dependencies are downloaded and built automatically during docker build command.

Docker build

You need Docker installed.

Enter into Shrimp's folder and run docker build command:

cd shrimp-demo
docker build -t shrimpdemo .

All necessary dependencies will be downloaded, configured and built inside Docker's image.

Then you can start Docker's image:

docker run -p 8080:80 \
  --mount type=bind,source=YOUR-PATH,destination=/root/images,readonly \

where YOUR-PATH is a path to your images.

Build with Mxx_ru

First of all you need to download, configure and install ImageMagick and all its dependencies. ImageMagick and all necessary image encoders/decoders should be installed in your system before you start building Shrimp. You can take a look onto Dockerfile to see how it can be done.

To build Shrimp from repository you need to install Mxx_ru or above:

apt-get install ruby
gem install Mxx_ru

Mxx_ru helps to download necessary dependencies and used as a build tool.

Clone repo and download dependencies:

hg clone
cd shrimp-demo

Once you get Shrimp sources and its dependencies you can build it.

# Start with repository root directory
cd dev
# Build and run unit-tests.
ruby build.rb --mxx-cpp-release
# See in 'target/release' directory.


Shrimp is distributed under GNU Affero GPL v.3 license (see LICENSE and AGPL files).

For the license of asio library see COPYING file in asio distributive.

For the license of nodejs/http-parser library see LICENSE file in nodejs/http-parser distributive.

For the license of fmtlib see LICENSE file in fmtlib distributive.

For the license of SObjectizer library see LICENSE file in SObjectizer distributive.

For the license of clara library see LICENSE file in clara distributive.

For the license of CATCH library see LICENSE file in CATCH distributive.