Docs: fix style and typos and add testing instructions.

Author: bavshin-f5

README.md

@@ -16,7 +16,7 @@ certificate management ([ACMEv2]) protocol.
 
 ### Requirements
 
-- Regular NGINX build dependencies: C compliler, make, PCRE2, Zlib
+- Regular NGINX build dependencies: C compiler, make, PCRE2, Zlib
 - System-wide installation of OpenSSL 1.1.1 or later
 - Rust toolchain (1.81.0 or later)
 - [libclang] for rust-bindgen
@@ -25,11 +25,11 @@ certificate management ([ACMEv2]) protocol.
 
 ### Building
 
-One way to build the module is to export a path to a pre-built nginx source
+One way to build the module is to export a path to a pre-built NGINX source
 tree and run `cargo`.
 
 ```sh
-# checkout, configure and build nginx at ../nginx
+# checkout, configure and build NGINX at ../nginx
 cd nginx-acme
 export NGINX_BUILD_DIR=$(realpath ../nginx/objs)
 cargo build --release
@@ -40,7 +40,7 @@ The result will be located at `target/release/libnginx_acme.so`.
 Another way is to use the provided config script:
 
 ```sh
-# in the nginx source directory
+# in the NGINX source directory
 auto/configure \
     --with-compat \
     --with-http_ssl_module \
@@ -52,9 +52,29 @@ The result will be located at `objs/ngx_http_acme_module.so`.
 Currently this method produces a slightly larger library, as we don't instruct
 the linker to perform LTO and remove unused code.
 
+### Testing
+
+The repository contains an integration test suite based on the [nginx-tests].
+The following command will build the module and run the tests:
+
+```sh
+# Path to the nginx source checkout, defaults to ../nginx if not specified.
+export NGINX_SOURCE_DIR=$(realpath ../nginx)
+# Path to the nginx-tests checkout; defaults to ../nginx/tests if not specified.
+export NGINX_TESTS_DIR=$(realpath ../nginx-tests)
+
+make test
+```
+
+Most of the tests require [pebble] test server binary in the path, or in a
+location specified via `TEST_NGINX_PEBBLE_BINARY` environment variable.
+
+[nginx-tests]: https://github.com/nginx/nginx-tests
+[pebble]: https://github.com/letsencrypt/pebble
+
 ## How to Use
 
-Add the module to the nginx configuration and configure as described below.
+Add the module to the NGINX configuration and configure as described below.
 Note that this module requires a [resolver] configuration in the `http` block.
 
 [resolver]: https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver
@@ -66,12 +86,12 @@ resolver 127.0.0.1:53;
 
 acme_issuer example {
     uri         https://acme.example.com/directory;
-    contact     [email protected];
-    state_path  /var/lib/nginx/acme-example;
+    # contact     [email protected];
+    state_path  /var/cache/nginx/acme-example;
     accept_terms_of_service;
 }
 
-acme_shared_zone zone=acme_shared:1M;
+acme_shared_zone zone=ngx_acme_shared:1M;
 
 server {
     listen 443 ssl;
@@ -82,6 +102,7 @@ server {
     ssl_certificate       $acme_certificate;
     ssl_certificate_key   $acme_certificate_key;
 
+    # do not parse the certificate on each request
     ssl_certificate_cache max=2;
 }
 
@@ -130,12 +151,13 @@ of the ACME server. This is the only mandatory parameter in the
 The account's private key used for request authentication.
 Accepted values:
 
-- `ecdsa:256/384/521` for `ES256` / `ES384` / `ES512` JSON Web Signature algorithms
-- `rsa:2048..4096` for `RS256` .
+- `ecdsa:256/384/521` for `ES256`, `ES384` or `ES512` JSON Web Signature
+  algorithms
+- `rsa:2048..4096` for `RS256`.
 - File path for an existing key, using one of the algorithms above.
 
 The generated account keys are preserved across reloads, but will be lost on
-restart unless [](#state_path) is configured.
+restart unless [state_path](#state_path) is configured.
 
 ### contact
 
@@ -171,7 +193,7 @@ the certificate of the ACME server.
 
 **Context:** acme_issuer
 
-Enables or disables verification of the ACME servier certificate.
+Enables or disables verification of the ACME server certificate.
 
 ### state_path
 
@@ -215,6 +237,9 @@ the module.
 The shared memory zone will be used to store the issued certificates, keys and
 challenge data for all the configured certificate issuers.
 
+The default zone size is sufficient to hold ~50 ECDSA prime256v1 keys or
+~35 RSA 2048 keys.
+
 ### acme_certificate
 
 **Syntax:** acme_certificate `issuer` [`identifier` ...] [ `key` = `alg[:size]` ]
@@ -245,12 +270,12 @@ The `ngx_http_acme_module` module defines following embedded
 variables, valid in the `server` block with the
 [acme_certificate](#acme_certificate) directive:
 
-### ``$acme_certificate``
+### `$acme_certificate`
 
 SSL certificate that can be passed to the
 [ssl_certificate](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate).
 
-### ``$acme_certificate_key``
+### `$acme_certificate_key`
 
 SSL certificate private key that can be passed to the
 [ssl_certificate_key](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate_key).