Micro-service for file storage and processing written in Go
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

228 lines
3.5 KiB

3 years ago
  1. # Lithium
  2. Micro-service for file storage and processing written in Go.
  3. ## Features
  4. - Image processing pipelines for various transformations
  5. - Web API for storing & retrieving files
  6. ## Requirements
  7. - [Go 1.17+](https://go.dev/)
  8. - [*Docker*](https://docs.docker.com/) (optional)
  9. ## Setup
  10. #### 1. Clone repository
  11. ```shell
  12. git clone git@gogs.informatik.hs-fulda.de:FabianVowie/Lithium.git
  13. ```
  14. #### 2. Pull dependencies
  15. ```shell
  16. go get
  17. ```
  18. #### 3. Build & start application
  19. ```shell
  20. go run .
  21. ```
  22. **Run using [Docker](https://docs.docker.com/) container**
  23. ```shell
  24. docker run --rm -p 8000:8000 -v "$PWD":/usr/src/lithium -w /usr/src/lithium golang:1.17 go run .
  25. ```
  26. ## Testing
  27. ```shell
  28. go test ./...
  29. ```
  30. ### Run tests in verbose logging mode
  31. ```shell
  32. go test ./... -v
  33. ```
  34. ### Run tests in [Docker](https://docs.docker.com/) container
  35. ```shell
  36. docker run --rm -v "$PWD":/usr/src/lithium -w /usr/src/lithium golang:1.17 go test ./...
  37. ```
  38. ## API
  39. ### `GET` `/`
  40. Show application information.
  41. **Example response**:
  42. ```json
  43. {
  44. "Name": "Lithium",
  45. "Version": "0.1.0"
  46. }
  47. ```
  48. ### `GET` `/{pipeline}`
  49. Show pipeline information.
  50. **Example response**:
  51. ```json
  52. {
  53. "name": "example pipeline",
  54. "slug": "example",
  55. "type": 0,
  56. "remove_metadata": false,
  57. "steps": [
  58. {
  59. "name": "resize image",
  60. "type": 0,
  61. "options": {
  62. "width": 1280,
  63. "height": 720,
  64. "upscale": false
  65. }
  66. }
  67. ],
  68. "output": {
  69. "format": 0,
  70. "quality": 90
  71. }
  72. }
  73. ```
  74. ## Configuration
  75. Config options can be adjusted via the [`settings.json`](settings.json) file in the root directory.
  76. ```json
  77. {
  78. "endpoint": "0.0.0.0:8000",
  79. "token": "changeme",
  80. "storage_provider": {
  81. "type": 0,
  82. "base_path": "assets"
  83. }
  84. }
  85. ```
  86. ## Pipelines
  87. The project uses a pipeline system defined by [JSON](https://en.wikipedia.org/wiki/JSON) files located in the [config](config) folder.
  88. Take a look at the [example pipeline configuration file](config/example.json).
  89. Available pipeline `type`s: `0` (Image), `1` (Video)
  90. ```json
  91. {
  92. "name": "example pipeline",
  93. "slug": "example",
  94. "type": 0,
  95. "removeMetadata": false,
  96. "steps": [],
  97. "output": {}
  98. }
  99. ```
  100. ### Images pipeline
  101. The image pipeline offers the following additional output options.
  102. Available `format` types: `0` (jpeg)
  103. The `quality` field can contain any integer between 1 and 100.
  104. ```json
  105. {
  106. "output": {
  107. "format": 0,
  108. "quality": 90
  109. }
  110. }
  111. ```
  112. ### Available pipeline steps
  113. Each pipeline step consists of an optional `name`, a predefined `type` and configurable `options`.
  114. See the available options below for more information.
  115. ```json
  116. {
  117. "name": "step name",
  118. "type": 0,
  119. "options": {}
  120. }
  121. ```
  122. #### Resizing images
  123. Resize an image by a given `width` and `height`.
  124. **Step definition**:
  125. ```json
  126. {
  127. "type": 0,
  128. "options": {
  129. "width": 1280,
  130. "height": 720
  131. }
  132. }
  133. ```
  134. #### Rotating images
  135. Rotate an image with a given `angle` in degrees.
  136. **Step definition**:
  137. ```json
  138. {
  139. "type": 1,
  140. "options": {
  141. "angle": 90.0
  142. }
  143. }
  144. ```
  145. #### Flipping images
  146. Flip an image with a given direction.
  147. Allowed values for the `direction` option are `"h"` (horizontal), `"v"` (vertical)
  148. **Step definition**:
  149. ```json
  150. {
  151. "type": 2,
  152. "options": {
  153. "direction": "h"
  154. }
  155. }
  156. ```
  157. #### Grayscale
  158. Convert the colorspace of an image into grayscale.
  159. **Step definition**:
  160. ```json
  161. {
  162. "type": 3
  163. }
  164. ```
  165. ## Authors
  166. - [Fabian Vowie](https://gogs.informatik.hs-fulda.de/FabianVowie)
  167. - [Roman Zipp](https://gogs.informatik.hs-fulda.de/roman.zipp)