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.

238 lines
3.6 KiB

3 years ago
3 years ago
3 years ago
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. **Required headers**:
  42. ```shell
  43. Authorization: Bearer <Token>
  44. ```
  45. **Example response**:
  46. ```json
  47. {
  48. "name": "Lithium",
  49. "version": "0.1.0"
  50. }
  51. ```
  52. ### `GET` `/{pipeline}`
  53. Show pipeline information.
  54. **Required headers**:
  55. ```shell
  56. Authorization: Bearer <Token>
  57. ```
  58. **Example response**:
  59. ```json
  60. {
  61. "name": "example pipeline",
  62. "slug": "example",
  63. "type": 0,
  64. "remove_metadata": false,
  65. "steps": [
  66. {
  67. "name": "resize image",
  68. "type": 0,
  69. "options": {
  70. "width": 1280,
  71. "height": 720,
  72. "upscale": false
  73. }
  74. }
  75. ],
  76. "output": {
  77. "format": 0,
  78. "quality": 90
  79. }
  80. }
  81. ```
  82. ## Configuration
  83. Config options can be adjusted via the [`settings.json`](settings.json) file in the root directory.
  84. ```json
  85. {
  86. "endpoint": "0.0.0.0:8000",
  87. "token": "changeme",
  88. "storage_provider": {
  89. "type": 0,
  90. "base_path": "assets"
  91. }
  92. }
  93. ```
  94. ## Pipelines
  95. The project uses a pipeline system defined by [JSON](https://en.wikipedia.org/wiki/JSON) files located in the [config](config) folder.
  96. Take a look at the [example pipeline configuration file](config/example.json).
  97. Available pipeline `type`s: `0` (Image), `1` (Video)
  98. ```json
  99. {
  100. "name": "example pipeline",
  101. "slug": "example",
  102. "type": 0,
  103. "removeMetadata": false,
  104. "steps": [],
  105. "output": {}
  106. }
  107. ```
  108. ### Images pipeline
  109. The image pipeline offers the following additional output options.
  110. Available `format` types: `0` (jpeg)
  111. The `quality` field can contain any integer between 1 and 100.
  112. ```json
  113. {
  114. "output": {
  115. "format": 0,
  116. "quality": 90
  117. }
  118. }
  119. ```
  120. ### Available pipeline steps
  121. Each pipeline step consists of an optional `name`, a predefined `type` and configurable `options`.
  122. See the available options below for more information.
  123. ```json
  124. {
  125. "name": "step name",
  126. "type": 0,
  127. "options": {}
  128. }
  129. ```
  130. #### Resizing images
  131. Resize an image by a given `width` and `height`.
  132. **Step definition**:
  133. ```json
  134. {
  135. "type": 0,
  136. "options": {
  137. "width": 1280,
  138. "height": 720
  139. }
  140. }
  141. ```
  142. #### Rotating images
  143. Rotate an image with a given `angle` in degrees.
  144. **Step definition**:
  145. ```json
  146. {
  147. "type": 1,
  148. "options": {
  149. "angle": 90.0
  150. }
  151. }
  152. ```
  153. #### Flipping images
  154. Flip an image with a given direction.
  155. Allowed values for the `direction` option are `"h"` (horizontal), `"v"` (vertical)
  156. **Step definition**:
  157. ```json
  158. {
  159. "type": 2,
  160. "options": {
  161. "direction": "h"
  162. }
  163. }
  164. ```
  165. #### Grayscale
  166. Convert the colorspace of an image into grayscale.
  167. **Step definition**:
  168. ```json
  169. {
  170. "type": 3
  171. }
  172. ```
  173. ## Authors
  174. - [Fabian Vowie](https://gogs.informatik.hs-fulda.de/FabianVowie)
  175. - [Roman Zipp](https://gogs.informatik.hs-fulda.de/roman.zipp)