Move documentation into README.md

README.md

@@ -0,0 +1,102 @@
+upload.pm
+=========
+
+This [Nginx][1] module implements the HTTP server's part of the XMPP extension
+[XEP-0363: HTTP File Upload][2]. It can be used with either ejabberd's
+[`mod_http_upload`][3] or Prosody's [`mod_http_upload_external`][4].
+
+Nginx setup
+-----------
+
+1. Create a directory and move `upload.pm` into it, e.g.:
+
+    ```sh
+    # mkdir -p /usr/local/lib/perl
+    # wget -P /usr/local/lib/perl https://git.io/fNZgL
+    ```
+
+2. Install the [`ngx_http_perl_module`][5]. On Debian/Ubuntu-based
+   distributions, the package is called `libnginx-mod-http-perl`, on
+   RedHat/CentOS-based distributions, it's `nginx-mod-http-perl`.
+
+3. Add the following snippets to the appropriate sections of your Nginx
+   configuration:
+
+    ```nginx configuration file
+    # This directive was probably added by the distribution package already:
+    load_module modules/ngx_http_perl_module.so;
+
+    http {
+        # Add the following two lines to the existing "http" block.
+        perl_modules /usr/local/lib/perl; # Path to upload.pm.
+        perl_require upload.pm;
+    }
+
+    server {
+        # Specify directives such as "listen", "server_name", and TLS-related
+        # settings for the "server" that handles the uploads.
+
+        # Uploaded files will be stored below this directory:
+        root /var/www/upload;
+
+        # Specify this "location" block (if you don't use "/", see below):
+        location / {
+            perl upload::handle;
+        }
+
+        # Upload file size limit (default: 1m), also specified in your XMPP
+        # server's upload module configuration (see below):
+        client_max_body_size 100m;
+    }
+    ```
+
+4. Open `upload.pm` in an editor and adjust the configuration at the top of the
+   file:
+
+   - The `$external_secret` must match the one specified in your XMPP server's
+     upload module configuration (see below).
+
+   - If the root path of the upload URIs (the `location` specified in the Nginx
+     `server` block) isn't `/` but `/some/prefix/`, `$uri_prefix_components`
+     must be set to the number of directory levels. So, for `/some/prefix/`, it
+     would be `2`.
+
+ejabberd setup
+--------------
+
+Let the [`mod_http_upload`][3] option `put_url` point to Nginx, and specify
+exactly the same `external_secret` as in the `upload.pm` settings:
+
+```yaml
+modules:
+  mod_http_upload:
+    put_url: "https://upload.example.com"
+    external_secret: "it-is-secret"
+    max_size: 104857600 # 100 MiB, also specified in the Nginx configuration.
+```
+
+Prosody setup
+-------------
+
+Let the [`mod_http_upload_external`][4] option `http_upload_external_base_url`
+point to Nginx, and specify exactly the same `http_upload_external_secret` as in
+the `upload.pm` settings:
+
+```lua
+http_upload_external_base_url = "https://upload.example.com"
+http_upload_external_secret = "it-is-secret"
+http_upload_external_file_size_limit = 104857600 -- 100 MiB
+```
+
+Contact
+-------
+
+If you have any questions, you could ask in the ejabberd room:
+`ejabberd@conference.process-one.net` (the maintainer of this module is usually
+joined as _Holger_).
+
+[1]: https://nginx.org/en/
+[2]: https://xmpp.org/extensions/xep-0363.html
+[3]: https://docs.ejabberd.im/admin/configuration/#mod-http-upload
+[4]: https://modules.prosody.im/mod_http_upload_external.html#implementation
+[5]: https://nginx.org/en/docs/http/ngx_http_perl_module.html

upload.pm

@@ -1,5 +1,6 @@
-# See: https://modules.prosody.im/mod_http_upload_external.html
+# Nginx module to handle file uploads and downloads for ejabberd's
-#
+# mod_http_upload or Prosody's mod_http_upload_external.
+
 # Copyright 2018 Holger Weiss <holger@zedat.fu-berlin.de>
 #
 # Permission to use, copy, modify, and/or distribute this software for any
@@ -16,43 +17,12 @@
 
 package upload;
 
-#### INSTALLATION
+## CONFIGURATION -----------------------------------------------------
-
-# 1) Create a directory and move this module into it, e.g., /usr/local/lib/perl.
-#
-# 2) Install ngx_http_perl_module (on Debian/Ubuntu: libnginx-mod-http-perl).
-#
-# 3) Add the following snippets to the appropriate sections of your Nginx
-#    configuration (the "load_module" directive might've been added by a
-#    distribution package already):
-#
-#    load_module modules/ngx_http_perl_module.so;
-#    http {
-#        # [...]
-#        perl_modules /usr/local/lib/perl;
-#        perl_require upload.pm;
-#    }
-#    server {
-#        # [...]
-#        location / {
-#            perl upload::handle;
-#        }
-#    }
-#
-# 4) Adjust the configuration below. Notes:
-#
-#    - The $external_secret must match the one specified in your XMPP server's
-#      upload module configuration.
-#    - If the root path of the upload URIs (i.e., the "location" specified in
-#      Nginx) isn't "/" but "/some/prefix/", $uri_prefix_components must be set
-#      to the number of directory levels; for "/some/prefix/", it would be 2.
-
-#### CONFIGURATION
 
 my $external_secret = 'it-is-secret';
+my $uri_prefix_components = 0;
 my $file_mode = 0640;
 my $dir_mode  = 0750;
-my $uri_prefix_components = 0;
 my %custom_headers = (
     'Access-Control-Allow-Origin' => '*',
     'Access-Control-Allow-Methods' => 'OPTIONS, HEAD, GET, PUT',
@@ -60,7 +30,7 @@ my %custom_headers = (
     'Access-Control-Allow-Credentials' => 'true',
 );
 
-#### END OF CONFIGURATION
+## END OF CONFIGURATION ----------------------------------------------
 
 use warnings;
 use strict;