diff --git a/README.md b/README.md new file mode 100644 index 0000000..8b8f125 --- /dev/null +++ b/README.md @@ -0,0 +1,228 @@ +# Lithium + +Micro-service for file storage and processing written in Go. + +## Features + +- Image processing pipelines for various transformations +- Web API for storing & retrieving files + +## Requirements + +- [Go 1.17+](https://go.dev/) +- [*Docker*](https://docs.docker.com/) (optional) + +## Setup + +#### 1. Clone repository + +```shell +git clone git@gogs.informatik.hs-fulda.de:FabianVowie/Lithium.git +``` + +#### 2. Pull dependencies + +```shell +go get +``` + +#### 3. Build & start application + +```shell +go run . +``` + +**Run using [Docker](https://docs.docker.com/) container** + +```shell +docker run --rm -p 8000:8000 -v "$PWD":/usr/src/lithium -w /usr/src/lithium golang:1.17 go run . +``` + +## Testing + +```shell +go test ./... +``` + +### Run tests in verbose logging mode + +```shell +go test ./... -v +``` + +### Run tests in [Docker](https://docs.docker.com/) container + +```shell +docker run --rm -v "$PWD":/usr/src/lithium -w /usr/src/lithium golang:1.17 go test ./... +``` + +## API + +### `GET` `/` + +Show application information. + +**Example response**: + +```json +{ + "Name": "Lithium", + "Version": "0.1.0" +} +``` + +### `GET` `/{pipeline}` + +Show pipeline information. + +**Example response**: + +```json +{ + "name": "example pipeline", + "slug": "example", + "type": 0, + "remove_metadata": false, + "steps": [ + { + "name": "resize image", + "type": 0, + "options": { + "width": 1280, + "height": 720, + "upscale": false + } + } + ], + "output": { + "format": 0, + "quality": 90 + } +} +``` + +## Configuration + +Config options can be adjusted via the [`settings.json`](settings.json) file in the root directory. + +```json +{ + "endpoint": "0.0.0.0:8000", + "token": "changeme", + "storage_provider": { + "type": 0, + "base_path": "assets" + } +} +``` + +## Pipelines + +The project uses a pipeline system defined by [JSON](https://en.wikipedia.org/wiki/JSON) files located in the [config](config) folder. +Take a look at the [example pipeline configuration file](config/example.json). + +Available pipeline `type`s: `0` (Image), `1` (Video) + +```json +{ + "name": "example pipeline", + "slug": "example", + "type": 0, + "removeMetadata": false, + "steps": [], + "output": {} +} +``` + +### Images pipeline + +The image pipeline offers the following additional output options. + +Available `format` types: `0` (jpeg) +The `quality` field can contain any integer between 1 and 100. + +```json +{ + "output": { + "format": 0, + "quality": 90 + } +} +``` + +### Available pipeline steps + +Each pipeline step consists of an optional `name`, a predefined `type` and configurable `options`. +See the available options below for more information. + +```json +{ + "name": "step name", + "type": 0, + "options": {} +} +``` + +#### Resizing images + +Resize an image by a given `width` and `height`. + +**Step definition**: + +```json +{ + "type": 0, + "options": { + "width": 1280, + "height": 720 + } +} +``` + +#### Rotating images + +Rotate an image with a given `angle` in degrees. + +**Step definition**: + +```json +{ + "type": 1, + "options": { + "angle": 90.0 + } +} +``` + +#### Flipping images + +Flip an image with a given direction. +Allowed values for the `direction` option are `"h"` (horizontal), `"v"` (vertical) + +**Step definition**: + +```json +{ + "type": 2, + "options": { + "direction": "h" + } +} +``` + +#### Grayscale + +Convert the colorspace of an image into grayscale. + +**Step definition**: + +```json +{ + "type": 3 +} +``` + +## Authors + +- [Fabian Vowie](https://gogs.informatik.hs-fulda.de/FabianVowie) +- [Roman Zipp](https://gogs.informatik.hs-fulda.de/roman.zipp) diff --git a/lithium.md b/lithium.md deleted file mode 100644 index 6d0ed5c..0000000 --- a/lithium.md +++ /dev/null @@ -1,16 +0,0 @@ -# Lithium - -Micro-service for file storage and processing. - -## Features - -- File storing with various providers - - S3 (or S3 compatible like MinIO) - - Locally (for development purposes) -- File processing "pipelines" for various formats - - Compression, Resizing for images - - Encoding for videos - - Remove metadata (e.g. EXIF) -- File-based configuration for pipelines - - JSON/YAML/TOML? -- Web api to store and retrieve files