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
5bfcacab58
morphus/README.md
cupcakearmy 5bfcacab58
readme
2022-05-29 01:49:55 +02:00

293 lines
12 KiB
Markdown
Raw Blame History

# morphus
<p align="center">
<br>
<img src="./design/round.png" width=150 />
<br><br>
</p>
<a href="https://discord.gg/nuby6RnxZt">
<img alt="discord" src="https://img.shields.io/discord/252403122348097536?style=for-the-badge" />
<img alt="docker pulls" src="https://img.shields.io/docker/pulls/cupcakearmy/morphus?style=for-the-badge" />
<img alt="Docker image size badge" src="https://img.shields.io/docker/image-size/cupcakearmy/morphus?style=for-the-badge" />
<img alt="Latest version" src="https://img.shields.io/github/v/release/cupcakearmy/moprhus?style=for-the-badge" />
</a>
A lightweight image resizing and effect proxy that caches image transformations.
The heavy lifting is done by [`libvips`](https://github.com/libvips/libvips) and [`sharp`](https://github.com/lovell/sharp)
> **⚠️ Currently under development**
## 🌈 Features
- Config driven
- Domain protection
- Host verification
- Multiple storage adapters (Local, Minio, S3, GCP)
- Auto format based on `Accept` header and `user-agent`
- ETag caching
- Presets and optinal forcing of presets
## 🏗 Installation
The easies way to run is using docker.
```yaml
# morphus.yaml
allowedDomains:
- !regexp ^https?:\/\/images.unsplash.com
```
```yaml
# docker-compose.yaml
version: '3.8'
services:
app:
image: cupcakearmy/morphus
ports:
- '80:80'
```
```bash
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`
```yaml
# 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](https://sharp.pixelplumbing.com/api-resize#parameters) | `?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](https://getpino.io/#/docs/api?id=loggerlevel-string-gettersetter) 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](https://github.com/mozilla/node-convict/issues/399) | null | The domains that are allowed to be used as image sources. |
| `allowedHosts` | [unsupported for now as ENV](https://github.com/mozilla/node-convict/issues/399) | 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
```yaml
# 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
```yaml
# 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
```yaml
# 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.
```yaml
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.
```yaml
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.
```yaml
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.
```yaml
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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-crossorigin)
### 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` |
Reference in New Issue View Git Blame Copy Permalink