cupcakearmy/morphus
1
0
Fork 0
mirror of https://github.com/cupcakearmy/morphus.git synced 2024-12-22 08:06:30 +00:00
Code Issues Packages Projects Releases Wiki Activity
008d1c949d
morphus/README.md
cupcakearmy 008d1c949d
stuff
2022-10-18 13:58:37 +02:00

12 KiB
Raw Blame History

morphus




discord docker pulls Docker image size badge Latest version

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

⚠️ Currently under development

🌈 Features

  • Config driven
  • Domain protection
  • Host verification
  • Multiple storage adapters (Local, Minio, S3, GCP)
  • Auto format based on Accept header
  • ETag caching
  • Presets and optional forcing of presets

🏗 Installation

The easies way to run is using docker.

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

# docker-compose.yaml
version: '3.8'

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

docker-compose up

For more realistic docker-compose files check the docker directory.

🎪 Examples

Simple resize: ?width=2000&resize=contain

https://my-morphus.org/api/image?width=2000&resize=contain&url=https://images.unsplash.com/photo-1636839270984-1f7cbc2b4c4b

Chose a format: ?format=webp

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

Chose a format with a given quality: ?format=webp|quality:90

https://my-morphus.org/api/image?format=webp|quality:90&width=2000&resize=contain&url=https://images.unsplash.com/photo-1636839270984-1f7cbc2b4c4b

With some transformation operations: ?op=rotate|angle:90&op=sharpen|sigma:1,flat:2

This is transforming the image once by rotate with the argument angle: 90 and sharpen with the arguments of sigma: 1 and flat: 2.

https://my-morphus.org/api/image?width=2000&resize=contain&op=rotate|angle:90&op=sharpen|sigma:1,flat:2&url=https://images.unsplash.com/photo-1636839270984-1f7cbc2b4c4b

With custom presets: ?preset=thumbnail

# morphus.yaml
presets:
  thumbnail: ?width=300&height=150&resize=contain

https://my-morphus.org/api/image?preset=thumbnail&url=https://images.unsplash.com/photo-1636839270984-1f7cbc2b4c4b

💻 Usage

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.
logLevel LOG_LEVEL info The log level to use. Possible values: trace, debug, info, warn, error, fatal, silent.
presets not available null Predefined presets. See below for an example.
onlyAllowPresets ONLY_ALLOW_PRESETS false Whether to allow only presets. This can prevent unfair usage.
allowedDomains unsupported for now as ENV null The domains that are allowed to be used as image sources.
allowedHosts unsupported for now as ENV 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. Possible values: local, minio, s3, gcs.

Storage Drivers

Local

Config Environment Default Description
local.assets LOCAL_ASSETS ./assets The path to the assets folder

Minio

Config Environment Default Description
minio.accessKey MINIO_ACCESS_KEY The access key for Minio
minio.secretKey MINIO_SECRET_KEY The secret key for Minio
minio.endpoint MINIO_ENDPOINT The endpoint for Minio
minio.bucket MINIO_BUCKET The bucket to use for Minio
minio.region MINIO_REGION The region for Minio
Example
# morphus.yaml

storage: minio
minio:
  accessKey: minioadmin
  secretKey: minioadmin
  bucket: morphus
  endpoint: http://localhost:9000

AWS S3

Config Environment Default Description
s3.bucket S3_BUCKET The S3 bucket to use
s3.region S3_REGION The S3 region to use
s3.accessKey S3_ACCESS_KEY_ID The S3 access key id to use
s3.secretKey S3_SECRET_ACCESS_KEY The S3 secret access key to use
Example
# morphus.yaml

storage: s3

s3:
  accessKey: abc
  secretKey: def
  bucket: morphus

Google Cloud Storage

Config Environment Default Description
gcs.bucket GCS_BUCKET The GCS bucket to use
gcs.keyFilename GCS_KEY_FILENAME The GCS key file to use

Due to Google Cloud requiring a keyfile, that keyfile needs to be available to morphus. In docker this means passing it into the volume for example.

Example
# morphus.yaml

storage: gcs
gcs:
  bucket: morphus
  keyFilename: keyfile.json

Presets

With the help of presets you can give predefined sets of operations and transformations. Clients then can use the presets without specifying the exact parameters.

The syntax is an object that maps a preset name to a value. The value is a valid url query.

presets:
  sm: ?format=webp|quality:90&width=500&resize=contain
  md: ?format=webp|quality:90&width=1000&resize=contain
  lg: ?format=webp|quality:90&width=2000&resize=contain

A client can the request an image with the following url

https://my-morphus.org/api/image?preset=sm&url=https://images.unsplash.com/photo-1636839270984-1f7cbc2b4c4b

Only allow presets

This feature can help reduce abuse of the server by only allowing. When onlyAllowPresets is set no other parameter is allowed besides url and preset. If possible it's recommended to turn this on.

onlyAllowPresets: true

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