morphus/README.md

morphus 🖼

A lightweight image resizing and effect proxy that caches image transformations. The heavy lifting is done by libvips and sharp

🌈 Features

• Config driven
• Domain protection
• Host verification
• Multiple storage adapters (Local, Minio, S3)
• Caniuse based automatic formatting
• ETag caching

🏗 Installation

The easies way to run is using docker

allowedDomains:
  - !regexp ^https?:\/\/images.unsplash.com

version: '3.8'

services:
  app:
    image: cupcakearmy/morphus
    ports:
      - '80:80'

docker-compose up

💻 Usage

Example

<img
  url="https://my-morphus.org/api/image?url=https://images.unsplash.com/photo-1636839270984-1f7cbc2b4c4b?format=webp&resize=contain&width=800"
/>

Parameter	Syntax	Example
url	URL	?url=https://cdn.example.org/dog-full-res.png
format	ComplexParameter	?format=webp ?format=webp|quality:90,progressive:true
resize	sharp.fit	?resize=contain
width	number	?width=500
height	number	?width=500
op	ComplexParameter[]	?op=rotate|angle:90&op=sharpen|sigma:1,flat:2

ComplexParameter

The syntax for the ComplexParameter is as follows:

Without options

?param=<name>

With two options

?param=<name>|optionA:1,optionB:true

⚙️ Configuration

Config files are searched in the current working directory under morphus.yaml.

Configuration can be done either thorough config files or env variables. The usage of a config file is recommended. Below is a table of available configuration options, for more details see below.

Config	Environment	Default	Description
port	PORT	80	The port to bind
address	ADDRESS	127.0.0.1	The address to bind
allowedDomains	ALLOWED_DOMAIN	null	The domains that are allowed to be used as image sources
allowedHosts	ALLOWED_HOSTS	null	The hosts that are allowed to access the images
cleanUrls	CLEAN_URL	Fragment	Whether source URLs are cleaned
maxAge	MAX_AGE	1d	How long the served images are marked as cached, after that ETag is used to revalidate
storage	STORAGE	Local	The storage driver to use
local_assets	LOCAL_ASSETS	./assets	Directory where the local storage driver persists files

Allowed Domains

Allowed domains are a way to secure the service by only allowing certain remote domains as possible sources of images.

You can provide a string which will match as prefix or RegExp that allow for more powerful control.

If omitted every domain is allowed.

allowedDomains:
  # This will match any URL that starts with the string.
  - https://my.cloud.org

  # For regexp you need to add the !regexp tag in from of it.
  - !regexp ^https?:\/\/images.unsplash.com

Allowed Hosts

Same syntax as for allowed domains.

Allowed hosts enables you to whitelist a number of origins.

If ommtted any origin is allowed.

allowedHosts:
  - https://my.cloud.org

Note

When using the url in an <img> tag you need to add the <img crossorigin="anonymous"> attribute to enable sending the origin header to the server. Read more here

Clean URLs

This option allows cleaning the source URLs to remove duplicates. allowed options are off, fragment, query.

Example

Type	URL
Original	https://images.unsplash.com/photo-1636839270984-1f7cbc2b4c4b?lang=en#chapter1
off	https://images.unsplash.com/photo-1636839270984-1f7cbc2b4c4b?lang=en#chapter1
fragment	https://images.unsplash.com/photo-1636839270984-1f7cbc2b4c4b?lang=en
query	https://images.unsplash.com/photo-1636839270984-1f7cbc2b4c4b