Commit ac20700a authored by Alessio Parma's avatar Alessio Parma 🐔

readme

parent 8a82634f
Pipeline #151580852 canceled with stages
......@@ -10,18 +10,21 @@
Web service which exposes endpoints to generate thumbnails and to optimize images.
Thumbnailer heavily relies on the following command line tools:
Thumbnailer heavily relies on many open source command line tools. Just to name a few:
- [ImageMagick][imagemagick-website], used to generate thumbnails.
- [imagemin-cli][github-imagemin-cli], used to optimize images.
- [GraphicsMagick][graphicsmagick-website], used to generate thumbnails.
- [wkhtmltoimage][wkhtmltopdf-website], used to convert HTML files to images.
- [LibreOffice][libreoffice-website], used to convert Office files to images.
- [pngquant][pngquant-website], used to optimize PNG images and thumbnails.
Thumbnailer is used in production by the following products and companies:
- [Replycare][replycare-website], a startup whose goal is to innovate the relationship between patient and doctor.
- [Sharize][sharize-website], a marketing resources management (MRM) platform developed by [Finsa S.p.A.][finsa-website], an Italian consultancy firm.
- [Sharize][sharize-website], a marketing resources management (MRM) platform developed by [Finsa S.p.A.][finsa-website],
an Italian consultancy firm.
Web service runs on ASP.NET Core and this repository contains a [.NET Standard client][nuget-package] which can be used to interact with it.
Web service runs on ASP.NET Core and this repository contains a [.NET Standard client][nuget-package]
which can be used to interact with it.
## Table of Contents
......@@ -45,7 +48,24 @@ docker run -it -e Security__AllowAnonymousAccess=true -p 8080:8080 pommalabs/thu
Local instance will be listening on port 8080 and will accept unauthenticated requests.
**TODO: Document web service settings.**
Docker image can be configured using the following environment variables:
| Environment variable | Notes | Default value |
| ------------------------------------------------ | ------------------------------------------------ | -------------- |
| `Cache__Lifetime` | How long each cache entry will live. | 10 minutes |
| `Database__ConnectionString` | Connection string of a SQL database. | |
| `Database__Provider` | Provider (`None`, `PostgreSql`, `SqlServer`). | `None` |
| `Security__AcceptApiKeysViaHeaderParameter` | Accept API keys via header parameter. | `true` |
| `Security__AcceptApiKeysViaQueryStringParameter` | Accept API keys via query string parameter. | `false` |
| `Security__AllowAnonymousAccess` | Allow anonymous users to consume services. | `false` |
| `Security__ApiKeys__X__ExpiresAt` | If not specified, API key will not expire. | |
| `Security__ApiKeys__X__Name` | Descriptive name of API key at index X. | |
| `Security__ApiKeys__X__Value` | Value of API key at index X. | |
| `Security__CommandTimeout` | Timeout for low level commands. | 1 minute |
| `Security__MaxFileDownloadSizeInBytes` | How many bytes are allowed for remote downloads. | 64 MB |
| `Security__MaxFileUploadSizeInBytes` | How many bytes are allowed for uploads. | 32 MB |
| `Website__Enabled` | Expose the public website. | `false` |
| `Website__GoogleAnalyticsPropertyId` | Google Analytics property ID. | |
## Usage
......@@ -65,16 +85,18 @@ TODO: Document a simple call.
Anyway, you can use the [test files][thumbnailer-samples] as a quick reference
to find out what the web service really supports.
Inside each "format" folder you will find a copy of the latest thumbnails, that is,
for each file you will find the most recent copy of its thumbnail.
Some notable formats which are **not** supported:
for each file you will find the most recent copy of its thumbnail.
However, not every content type for which a thumbnail could be "theoretically" generated is supported.
Some notable formats which are **not** supported are the following:
- PSD files represent a security issue since GraphicsMagick support is not complete.
As a matter of fact, [their support in GraphicsMagick has been disabled][graphicsmagick-psd-disabled].
## API
Please check OpenAPI docs on your instance (just visit the `/swagger` endpoint)
or head to the [demo instance Swagger endpoint](https://thumbnailer.pommalabs.xyz/swagger/index.html).
Please check OpenAPI docs on your instance (just visit the `/swagger` endpoint)
or head to the [demo instance Swagger endpoint](https://thumbnailer.pommalabs.xyz/swagger/index.html).
Each endpoint has been documented using the OpenAPI specification.
### RapidAPI
......@@ -100,22 +122,23 @@ MIT © 2019-2020 [Alessio Parma][personal-website]
[docker-repository]: https://hub.docker.com/repository/docker/pommalabs/thumbnailer
[docker-stars-badge]: https://img.shields.io/docker/stars/pommalabs/thumbnailer?style=flat-square
[finsa-website]: https://www.finsa.it/
[github-imagemin-cli]: https://github.com/imagemin/imagemin-cli
[github-standard-readme]: https://github.com/RichardLitt/standard-readme
[github-standard-readme-badge]: https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square
[gitlab-pipeline-status-badge]: https://gitlab.com/pommalabs/thumbnailer/badges/master/pipeline.svg?style=flat-square
[gitlab-pipelines]: https://gitlab.com/pommalabs/thumbnailer/pipelines
[gitlab-pomma89]: https://gitlab.com/pomma89
[graphicsmagick-psd-disabled]: http://www.graphicsmagick.org/NEWS.html#may-30-2016
[imagemagick-website]: https://imagemagick.org/
[graphicsmagick-website]: http://www.graphicsmagick.org/
[libreoffice-website]: https://www.libreoffice.org/
[nuget-downloads-badge]: https://img.shields.io/nuget/dt/PommaLabs.Thumbnailer.Client?style=flat-square
[nuget-package]: https://www.nuget.org/packages/PommaLabs.Thumbnailer.Client/
[nuget-version-badge]: https://img.shields.io/nuget/v/PommaLabs.Thumbnailer.Client?style=flat-square
[paypal-donations]: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ELJWKEYS9QGKA
[paypal-donations-badge]: https://img.shields.io/badge/Donate-PayPal-green.svg?style=flat-square
[personal-website]: https://pommalabs.xyz/
[pngquant-website]: https://pngquant.org/
[rapidapi-endpoints]: https://rapidapi.com/pommalabs-pommalabs-default/api/thumbnailer1/endpoints
[replycare-website]: https://www.replycare.com/
[sharize-website]: https://www.sharize.io/
[thumbnailer-samples]: https://gitlab.com/pommalabs/thumbnailer/-/tree/master/tests/PommaLabs.Thumbnailer.Tester/samples
[wkhtmltopdf-website]: https://wkhtmltopdf.org/
\ No newline at end of file
[wkhtmltopdf-website]: https://wkhtmltopdf.org/
......@@ -39,7 +39,7 @@ public sealed class DatabaseConfiguration
private string? _connectionString;
/// <summary>
/// Connection string.
/// Connection string of a SQL database.
/// </summary>
public string ConnectionString
{
......
......@@ -49,7 +49,7 @@ public sealed class SecurityConfiguration
public bool AcceptApiKeysViaQueryStringParameter { get; set; } = false;
/// <summary>
/// Allows anonymous users to consume services. Defaults to false, because anonymous users
/// Allow anonymous users to consume services. Defaults to false, because anonymous users
/// can overload the web service, unless a rate limiting process is active.
/// </summary>
public bool AllowAnonymousAccess { get; set; } = false;
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment