diff options
Diffstat (limited to 'nixos/modules/services/web-apps/pict-rs.xml')
| -rw-r--r-- | nixos/modules/services/web-apps/pict-rs.xml | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/nixos/modules/services/web-apps/pict-rs.xml b/nixos/modules/services/web-apps/pict-rs.xml new file mode 100644 index 00000000000..bf129f5cc2a --- /dev/null +++ b/nixos/modules/services/web-apps/pict-rs.xml @@ -0,0 +1,162 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-pict-rs"> + <title>Pict-rs</title> + <para> + pict-rs is a a simple image hosting service. + </para> + <section xml:id="module-services-pict-rs-quickstart"> + <title>Quickstart</title> + <para> + the minimum to start pict-rs is + </para> + <programlisting language="bash"> +services.pict-rs.enable = true; +</programlisting> + <para> + this will start the http server on port 8080 by default. + </para> + </section> + <section xml:id="module-services-pict-rs-usage"> + <title>Usage</title> + <para> + pict-rs offers the following endpoints: - + <literal>POST /image</literal> for uploading an image. Uploaded + content must be valid multipart/form-data with an image array + located within the <literal>images[]</literal> key + </para> + <programlisting> +This endpoint returns the following JSON structure on success with a 201 Created status +```json +{ + "files": [ + { + "delete_token": "JFvFhqJA98", + "file": "lkWZDRvugm.jpg" + }, + { + "delete_token": "kAYy9nk2WK", + "file": "8qFS0QooAn.jpg" + }, + { + "delete_token": "OxRpM3sf0Y", + "file": "1hJaYfGE01.jpg" + } + ], + "msg": "ok" +} +``` +</programlisting> + <itemizedlist> + <listitem> + <para> + <literal>GET /image/download?url=...</literal> Download an + image from a remote server, returning the same JSON payload as + the <literal>POST</literal> endpoint + </para> + </listitem> + <listitem> + <para> + <literal>GET /image/original/{file}</literal> for getting a + full-resolution image. <literal>file</literal> here is the + <literal>file</literal> key from the <literal>/image</literal> + endpoint’s JSON + </para> + </listitem> + <listitem> + <para> + <literal>GET /image/details/original/{file}</literal> for + getting the details of a full-resolution image. The returned + JSON is structured like so: + <literal>json { "width": 800, "height": 537, "content_type": "image/webp", "created_at": [ 2020, 345, 67376, 394363487 ] }</literal> + </para> + </listitem> + <listitem> + <para> + <literal>GET /image/process.{ext}?src={file}&...</literal> + get a file with transformations applied. existing + transformations include + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>identity=true</literal>: apply no changes + </para> + </listitem> + <listitem> + <para> + <literal>blur={float}</literal>: apply a gaussian blur to + the file + </para> + </listitem> + <listitem> + <para> + <literal>thumbnail={int}</literal>: produce a thumbnail of + the image fitting inside an <literal>{int}</literal> by + <literal>{int}</literal> square using raw pixel sampling + </para> + </listitem> + <listitem> + <para> + <literal>resize={int}</literal>: produce a thumbnail of + the image fitting inside an <literal>{int}</literal> by + <literal>{int}</literal> square using a Lanczos2 filter. + This is slower than sampling but looks a bit better in + some cases + </para> + </listitem> + <listitem> + <para> + <literal>crop={int-w}x{int-h}</literal>: produce a cropped + version of the image with an <literal>{int-w}</literal> by + <literal>{int-h}</literal> aspect ratio. The resulting + crop will be centered on the image. Either the width or + height of the image will remain full-size, depending on + the image’s aspect ratio and the requested aspect ratio. + For example, a 1600x900 image cropped with a 1x1 aspect + ratio will become 900x900. A 1600x1100 image cropped with + a 16x9 aspect ratio will become 1600x900. + </para> + </listitem> + </itemizedlist> + <para> + Supported <literal>ext</literal> file extensions include + <literal>png</literal>, <literal>jpg</literal>, and + <literal>webp</literal> + </para> + <para> + An example of usage could be + <literal>GET /image/process.jpg?src=asdf.png&thumbnail=256&blur=3.0</literal> + which would create a 256x256px JPEG thumbnail and blur it + </para> + </listitem> + <listitem> + <para> + <literal>GET /image/details/process.{ext}?src={file}&...</literal> + for getting the details of a processed image. The returned + JSON is the same format as listed for the full-resolution + details endpoint. + </para> + </listitem> + <listitem> + <para> + <literal>DELETE /image/delete/{delete_token}/{file}</literal> + or <literal>GET /image/delete/{delete_token}/{file}</literal> + to delete a file, where <literal>delete_token</literal> and + <literal>file</literal> are from the <literal>/image</literal> + endpoint’s JSON + </para> + </listitem> + </itemizedlist> + </section> + <section xml:id="module-services-pict-rs-missing"> + <title>Missing</title> + <itemizedlist spacing="compact"> + <listitem> + <para> + Configuring the secure-api-key is not included yet. The + envisioned basic use case is consumption on localhost by other + services without exposing the service to the internet. + </para> + </listitem> + </itemizedlist> + </section> +</chapter> |