commit 8346dc04b31bc4ade35bd15a72e6cc40c8ac2f73 · pyrox.dev/nixpkgs

nixos/modules/module-list.nix

···

       991
       991
        
         ./services/web-apps/nextcloud.nix

     

       992
       992
        
         ./services/web-apps/nexus.nix

     

       993
       993
        
         ./services/web-apps/node-red.nix

     

       994
       994
       +
         ./services/web-apps/pict-rs.nix

     

       994
       995
        
         ./services/web-apps/plantuml-server.nix

     

       995
       996
        
         ./services/web-apps/plausible.nix

     

       996
       997
        
         ./services/web-apps/pgpkeyserver-lite.nix

+88

nixos/modules/services/web-apps/pict-rs.md

···

       1
       1
       +
       # Pict-rs {#module-services-pict-rs}

     

       2
       2
       +
       

     

       3
       3
       +
       pict-rs is a  a simple image hosting service.

     

       4
       4
       +
       

     

       5
       5
       +
       ## Quickstart {#module-services-pict-rs-quickstart}

     

       6
       6
       +
       

     

       7
       7
       +
       the minimum to start pict-rs is

     

       8
       8
       +
       

     

       9
       9
       +
       ```nix

     

       10
       10
       +
       services.pict-rs.enable = true;

     

       11
       11
       +
       ```

     

       12
       12
       +
       

     

       13
       13
       +
       this will start the http server on port 8080 by default.

     

       14
       14
       +
       

     

       15
       15
       +
       ## Usage {#module-services-pict-rs-usage}

     

       16
       16
       +
       

     

       17
       17
       +
       pict-rs offers the following endpoints:

     

       18
       18
       +
       - `POST /image` for uploading an image. Uploaded content must be valid multipart/form-data with an

     

       19
       19
       +
           image array located within the `images[]` key

     

       20
       20
       +
       

     

       21
       21
       +
           This endpoint returns the following JSON structure on success with a 201 Created status

     

       22
       22
       +
           ```json

     

       23
       23
       +
           {

     

       24
       24
       +
               "files": [

     

       25
       25
       +
                   {

     

       26
       26
       +
                       "delete_token": "JFvFhqJA98",

     

       27
       27
       +
                       "file": "lkWZDRvugm.jpg"

     

       28
       28
       +
                   },

     

       29
       29
       +
                   {

     

       30
       30
       +
                       "delete_token": "kAYy9nk2WK",

     

       31
       31
       +
                       "file": "8qFS0QooAn.jpg"

     

       32
       32
       +
                   },

     

       33
       33
       +
                   {

     

       34
       34
       +
                       "delete_token": "OxRpM3sf0Y",

     

       35
       35
       +
                       "file": "1hJaYfGE01.jpg"

     

       36
       36
       +
                   }

     

       37
       37
       +
               ],

     

       38
       38
       +
               "msg": "ok"

     

       39
       39
       +
           }

     

       40
       40
       +
           ```

     

       41
       41
       +
       - `GET /image/download?url=...` Download an image from a remote server, returning the same JSON

     

       42
       42
       +
           payload as the `POST` endpoint

     

       43
       43
       +
       - `GET /image/original/{file}` for getting a full-resolution image. `file` here is the `file` key from the

     

       44
       44
       +
           `/image` endpoint's JSON

     

       45
       45
       +
       - `GET /image/details/original/{file}` for getting the details of a full-resolution image.

     

       46
       46
       +
           The returned JSON is structured like so:

     

       47
       47
       +
           ```json

     

       48
       48
       +
           {

     

       49
       49
       +
               "width": 800,

     

       50
       50
       +
               "height": 537,

     

       51
       51
       +
               "content_type": "image/webp",

     

       52
       52
       +
               "created_at": [

     

       53
       53
       +
                   2020,

     

       54
       54
       +
                   345,

     

       55
       55
       +
                   67376,

     

       56
       56
       +
                   394363487

     

       57
       57
       +
               ]

     

       58
       58
       +
           }

     

       59
       59
       +
           ```

     

       60
       60
       +
       - `GET /image/process.{ext}?src={file}&...` get a file with transformations applied.

     

       61
       61
       +
           existing transformations include

     

       62
       62
       +
           - `identity=true`: apply no changes

     

       63
       63
       +
           - `blur={float}`: apply a gaussian blur to the file

     

       64
       64
       +
           - `thumbnail={int}`: produce a thumbnail of the image fitting inside an `{int}` by `{int}`

     

       65
       65
       +
               square using raw pixel sampling

     

       66
       66
       +
           - `resize={int}`: produce a thumbnail of the image fitting inside an `{int}` by `{int}` square

     

       67
       67
       +
               using a Lanczos2 filter. This is slower than sampling but looks a bit better in some cases

     

       68
       68
       +
           - `crop={int-w}x{int-h}`: produce a cropped version of the image with an `{int-w}` by `{int-h}`

     

       69
       69
       +
               aspect ratio. The resulting crop will be centered on the image. Either the width or height

     

       70
       70
       +
               of the image will remain full-size, depending on the image's aspect ratio and the requested

     

       71
       71
       +
               aspect ratio. For example, a 1600x900 image cropped with a 1x1 aspect ratio will become 900x900. A

     

       72
       72
       +
               1600x1100 image cropped with a 16x9 aspect ratio will become 1600x900.

     

       73
       73
       +
       

     

       74
       74
       +
           Supported `ext` file extensions include `png`, `jpg`, and `webp`

     

       75
       75
       +
       

     

       76
       76
       +
           An example of usage could be

     

       77
       77
       +
           ```

     

       78
       78
       +
           GET /image/process.jpg?src=asdf.png&thumbnail=256&blur=3.0

     

       79
       79
       +
           ```

     

       80
       80
       +
           which would create a 256x256px JPEG thumbnail and blur it

     

       81
       81
       +
       - `GET /image/details/process.{ext}?src={file}&...` for getting the details of a processed image.

     

       82
       82
       +
           The returned JSON is the same format as listed for the full-resolution details endpoint.

     

       83
       83
       +
       - `DELETE /image/delete/{delete_token}/{file}` or `GET /image/delete/{delete_token}/{file}` to

     

       84
       84
       +
           delete a file, where `delete_token` and `file` are from the `/image` endpoint's JSON

     

       85
       85
       +
       

     

       86
       86
       +
       ## Missing {#module-services-pict-rs-missing}

     

       87
       87
       +
       

     

       88
       88
       +
       - 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.

+50

nixos/modules/services/web-apps/pict-rs.nix

···

       1
       1
       +
       { lib, pkgs, config, ... }:

     

       2
       2
       +
       with lib;

     

       3
       3
       +
       let

     

       4
       4
       +
         cfg = config.services.pict-rs;

     

       5
       5
       +
       in

     

       6
       6
       +
       {

     

       7
       7
       +
         meta.maintainers = with maintainers; [ happysalada ];

     

       8
       8
       +
         # Don't edit the docbook xml directly, edit the md and generate it:

     

       9
       9
       +
         # `pandoc pict-rs.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > pict-rs.xml`

     

       10
       10
       +
         meta.doc = ./pict-rs.xml;

     

       11
       11
       +
       

     

       12
       12
       +
         options.services.pict-rs = {

     

       13
       13
       +
           enable = mkEnableOption "pict-rs server";

     

       14
       14
       +
           dataDir = mkOption {

     

       15
       15
       +
             type = types.path;

     

       16
       16
       +
             default = "/var/lib/pict-rs";

     

       17
       17
       +
             description = ''

     

       18
       18
       +
               The directory where to store the uploaded images.

     

       19
       19
       +
             '';

     

       20
       20
       +
           };

     

       21
       21
       +
           address = mkOption {

     

       22
       22
       +
             type = types.str;

     

       23
       23
       +
             default = "127.0.0.1";

     

       24
       24
       +
             description = ''

     

       25
       25
       +
               The IPv4 address to deploy the service to.

     

       26
       26
       +
             '';

     

       27
       27
       +
           };

     

       28
       28
       +
           port = mkOption {

     

       29
       29
       +
             type = types.port;

     

       30
       30
       +
             default = 8080;

     

       31
       31
       +
             description = ''

     

       32
       32
       +
               The port which to bind the service to.

     

       33
       33
       +
             '';

     

       34
       34
       +
           };

     

       35
       35
       +
         };

     

       36
       36
       +
         config = lib.mkIf cfg.enable {

     

       37
       37
       +
           systemd.services.pict-rs = {

     

       38
       38
       +
             environment = {

     

       39
       39
       +
               PICTRS_PATH = cfg.dataDir;

     

       40
       40
       +
               PICTRS_ADDR = "${cfg.address}:${toString cfg.port}";

     

       41
       41
       +
             };

     

       42
       42
       +
             wantedBy = [ "multi-user.target" ];

     

       43
       43
       +
             serviceConfig = {

     

       44
       44
       +
               DynamicUser = true;

     

       45
       45
       +
               StateDirectory = "pict-rs";

     

       46
       46
       +
               ExecStart = "${pkgs.pict-rs}/bin/pict-rs";

     

       47
       47
       +
             };

     

       48
       48
       +
           };

     

       49
       49
       +
         };

     

       50
       50
       +
       }

+162

nixos/modules/services/web-apps/pict-rs.xml

···

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-pict-rs">

     

       2
       2
       +
         <title>Pict-rs</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           pict-rs is a a simple image hosting service.

     

       5
       5
       +
         </para>

     

       6
       6
       +
         <section xml:id="module-services-pict-rs-quickstart">

     

       7
       7
       +
           <title>Quickstart</title>

     

       8
       8
       +
           <para>

     

       9
       9
       +
             the minimum to start pict-rs is

     

       10
       10
       +
           </para>

     

       11
       11
       +
           <programlisting language="bash">

     

       12
       12
       +
       services.pict-rs.enable = true;

     

       13
       13
       +
       </programlisting>

     

       14
       14
       +
           <para>

     

       15
       15
       +
             this will start the http server on port 8080 by default.

     

       16
       16
       +
           </para>

     

       17
       17
       +
         </section>

     

       18
       18
       +
         <section xml:id="module-services-pict-rs-usage">

     

       19
       19
       +
           <title>Usage</title>

     

       20
       20
       +
           <para>

     

       21
       21
       +
             pict-rs offers the following endpoints: -

     

       22
       22
       +
             <literal>POST /image</literal> for uploading an image. Uploaded

     

       23
       23
       +
             content must be valid multipart/form-data with an image array

     

       24
       24
       +
             located within the <literal>images[]</literal> key

     

       25
       25
       +
           </para>

     

       26
       26
       +
           <programlisting>

     

       27
       27
       +
       This endpoint returns the following JSON structure on success with a 201 Created status

     

       28
       28
       +
       ```json

     

       29
       29
       +
       {

     

       30
       30
       +
           &quot;files&quot;: [

     

       31
       31
       +
               {

     

       32
       32
       +
                   &quot;delete_token&quot;: &quot;JFvFhqJA98&quot;,

     

       33
       33
       +
                   &quot;file&quot;: &quot;lkWZDRvugm.jpg&quot;

     

       34
       34
       +
               },

     

       35
       35
       +
               {

     

       36
       36
       +
                   &quot;delete_token&quot;: &quot;kAYy9nk2WK&quot;,

     

       37
       37
       +
                   &quot;file&quot;: &quot;8qFS0QooAn.jpg&quot;

     

       38
       38
       +
               },

     

       39
       39
       +
               {

     

       40
       40
       +
                   &quot;delete_token&quot;: &quot;OxRpM3sf0Y&quot;,

     

       41
       41
       +
                   &quot;file&quot;: &quot;1hJaYfGE01.jpg&quot;

     

       42
       42
       +
               }

     

       43
       43
       +
           ],

     

       44
       44
       +
           &quot;msg&quot;: &quot;ok&quot;

     

       45
       45
       +
       }

     

       46
       46
       +
       ```

     

       47
       47
       +
       </programlisting>

     

       48
       48
       +
           <itemizedlist>

     

       49
       49
       +
             <listitem>

     

       50
       50
       +
               <para>

     

       51
       51
       +
                 <literal>GET /image/download?url=...</literal> Download an

     

       52
       52
       +
                 image from a remote server, returning the same JSON payload as

     

       53
       53
       +
                 the <literal>POST</literal> endpoint

     

       54
       54
       +
               </para>

     

       55
       55
       +
             </listitem>

     

       56
       56
       +
             <listitem>

     

       57
       57
       +
               <para>

     

       58
       58
       +
                 <literal>GET /image/original/{file}</literal> for getting a

     

       59
       59
       +
                 full-resolution image. <literal>file</literal> here is the

     

       60
       60
       +
                 <literal>file</literal> key from the <literal>/image</literal>

     

       61
       61
       +
                 endpoint’s JSON

     

       62
       62
       +
               </para>

     

       63
       63
       +
             </listitem>

     

       64
       64
       +
             <listitem>

     

       65
       65
       +
               <para>

     

       66
       66
       +
                 <literal>GET /image/details/original/{file}</literal> for

     

       67
       67
       +
                 getting the details of a full-resolution image. The returned

     

       68
       68
       +
                 JSON is structured like so:

     

       69
       69
       +
                 <literal>json     {         &quot;width&quot;: 800,         &quot;height&quot;: 537,         &quot;content_type&quot;: &quot;image/webp&quot;,         &quot;created_at&quot;: [             2020,             345,             67376,             394363487         ]     }</literal>

     

       70
       70
       +
               </para>

     

       71
       71
       +
             </listitem>

     

       72
       72
       +
             <listitem>

     

       73
       73
       +
               <para>

     

       74
       74
       +
                 <literal>GET /image/process.{ext}?src={file}&amp;...</literal>

     

       75
       75
       +
                 get a file with transformations applied. existing

     

       76
       76
       +
                 transformations include

     

       77
       77
       +
               </para>

     

       78
       78
       +
               <itemizedlist spacing="compact">

     

       79
       79
       +
                 <listitem>

     

       80
       80
       +
                   <para>

     

       81
       81
       +
                     <literal>identity=true</literal>: apply no changes

     

       82
       82
       +
                   </para>

     

       83
       83
       +
                 </listitem>

     

       84
       84
       +
                 <listitem>

     

       85
       85
       +
                   <para>

     

       86
       86
       +
                     <literal>blur={float}</literal>: apply a gaussian blur to

     

       87
       87
       +
                     the file

     

       88
       88
       +
                   </para>

     

       89
       89
       +
                 </listitem>

     

       90
       90
       +
                 <listitem>

     

       91
       91
       +
                   <para>

     

       92
       92
       +
                     <literal>thumbnail={int}</literal>: produce a thumbnail of

     

       93
       93
       +
                     the image fitting inside an <literal>{int}</literal> by

     

       94
       94
       +
                     <literal>{int}</literal> square using raw pixel sampling

     

       95
       95
       +
                   </para>

     

       96
       96
       +
                 </listitem>

     

       97
       97
       +
                 <listitem>

     

       98
       98
       +
                   <para>

     

       99
       99
       +
                     <literal>resize={int}</literal>: produce a thumbnail of

     

       100
       100
       +
                     the image fitting inside an <literal>{int}</literal> by

     

       101
       101
       +
                     <literal>{int}</literal> square using a Lanczos2 filter.

     

       102
       102
       +
                     This is slower than sampling but looks a bit better in

     

       103
       103
       +
                     some cases

     

       104
       104
       +
                   </para>

     

       105
       105
       +
                 </listitem>

     

       106
       106
       +
                 <listitem>

     

       107
       107
       +
                   <para>

     

       108
       108
       +
                     <literal>crop={int-w}x{int-h}</literal>: produce a cropped

     

       109
       109
       +
                     version of the image with an <literal>{int-w}</literal> by

     

       110
       110
       +
                     <literal>{int-h}</literal> aspect ratio. The resulting

     

       111
       111
       +
                     crop will be centered on the image. Either the width or

     

       112
       112
       +
                     height of the image will remain full-size, depending on

     

       113
       113
       +
                     the image’s aspect ratio and the requested aspect ratio.

     

       114
       114
       +
                     For example, a 1600x900 image cropped with a 1x1 aspect

     

       115
       115
       +
                     ratio will become 900x900. A 1600x1100 image cropped with

     

       116
       116
       +
                     a 16x9 aspect ratio will become 1600x900.

     

       117
       117
       +
                   </para>

     

       118
       118
       +
                 </listitem>

     

       119
       119
       +
               </itemizedlist>

     

       120
       120
       +
               <para>

     

       121
       121
       +
                 Supported <literal>ext</literal> file extensions include

     

       122
       122
       +
                 <literal>png</literal>, <literal>jpg</literal>, and

     

       123
       123
       +
                 <literal>webp</literal>

     

       124
       124
       +
               </para>

     

       125
       125
       +
               <para>

     

       126
       126
       +
                 An example of usage could be

     

       127
       127
       +
                 <literal>GET /image/process.jpg?src=asdf.png&amp;thumbnail=256&amp;blur=3.0</literal>

     

       128
       128
       +
                 which would create a 256x256px JPEG thumbnail and blur it

     

       129
       129
       +
               </para>

     

       130
       130
       +
             </listitem>

     

       131
       131
       +
             <listitem>

     

       132
       132
       +
               <para>

     

       133
       133
       +
                 <literal>GET /image/details/process.{ext}?src={file}&amp;...</literal>

     

       134
       134
       +
                 for getting the details of a processed image. The returned

     

       135
       135
       +
                 JSON is the same format as listed for the full-resolution

     

       136
       136
       +
                 details endpoint.

     

       137
       137
       +
               </para>

     

       138
       138
       +
             </listitem>

     

       139
       139
       +
             <listitem>

     

       140
       140
       +
               <para>

     

       141
       141
       +
                 <literal>DELETE /image/delete/{delete_token}/{file}</literal>

     

       142
       142
       +
                 or <literal>GET /image/delete/{delete_token}/{file}</literal>

     

       143
       143
       +
                 to delete a file, where <literal>delete_token</literal> and

     

       144
       144
       +
                 <literal>file</literal> are from the <literal>/image</literal>

     

       145
       145
       +
                 endpoint’s JSON

     

       146
       146
       +
               </para>

     

       147
       147
       +
             </listitem>

     

       148
       148
       +
           </itemizedlist>

     

       149
       149
       +
         </section>

     

       150
       150
       +
         <section xml:id="module-services-pict-rs-missing">

     

       151
       151
       +
           <title>Missing</title>

     

       152
       152
       +
           <itemizedlist spacing="compact">

     

       153
       153
       +
             <listitem>

     

       154
       154
       +
               <para>

     

       155
       155
       +
                 Configuring the secure-api-key is not included yet. The

     

       156
       156
       +
                 envisioned basic use case is consumption on localhost by other

     

       157
       157
       +
                 services without exposing the service to the internet.

     

       158
       158
       +
               </para>

     

       159
       159
       +
             </listitem>

     

       160
       160
       +
           </itemizedlist>

     

       161
       161
       +
         </section>

     

       162
       162
       +
       </chapter>

+17

nixos/tests/pict-rs.nix

···

       1
       1
       +
       import ./make-test-python.nix ({ pkgs, lib, ... }:

     

       2
       2
       +
         {

     

       3
       3
       +
           name = "pict-rs";

     

       4
       4
       +
           meta.maintainers = with lib.maintainers; [ happysalada ];

     

       5
       5
       +
       

     

       6
       6
       +
           machine = { ... }: {

     

       7
       7
       +
             environment.systemPackages = with pkgs; [ curl jq ];

     

       8
       8
       +
             services.pict-rs.enable = true;

     

       9
       9
       +
           };

     

       10
       10
       +
       

     

       11
       11
       +
           testScript = ''

     

       12
       12
       +
             start_all()

     

       13
       13
       +
       

     

       14
       14
       +
             machine.wait_for_unit("pict-rs")

     

       15
       15
       +
             machine.wait_for_open_port("8080")

     

       16
       16
       +
           '';

     

       17
       17
       +
         })