draft: docs: Transfer Unit docs

config/_default/config.toml

@@ -44,7 +44,8 @@ enableGitInfo = true
     "taxonomyTerm"
   ]
   taxonomiesExcludedFromSitemap = ["tags", "categories", "doctypes"]
-
+  unitversion= "1.34.1"
+  unitversionv= "v1.34.1"
   #logo = ""
 
   # Version lists; used by the versions shortcode

content/includes/unit/howto_change_ownership.md

@@ -0,0 +1,18 @@
+Run the following command (as root) so Unit can access the application
+directory (If the application uses several directories, run the command for
+each one):
+
+```console
+# chown -R unit:unit /path/to/app/  # User and group that Unit's router runs as by default
+```
+
+
+{{< note >}}
+The **unit:unit** user-group pair is available only with
+[official packages]({{< relref "/unit/installation.md#installation-precomp-pkgs" >}})
+, Docker [images]({{< relref "/unit/installation.md#installation-docker" >}}),
+and some [third-party repos]({{< relref "/unit/installation.md#installation-community-repos" >}}). Otherwise, account names may differ; run the `ps aux | grep unitd` command to be sure.
+{{< /note >}}
+
+For further details, including permissions, see the
+[security checklist]({{< relref "/unit/howto/security.md#secutiry-apps" >}}).

content/includes/unit/howto_install_app.md

@@ -0,0 +1,2 @@
+Install {{ app }}'s [app-link]. Here, we install it at **/path/to/app/**; use
+a real path in your configuration.

content/includes/unit/howto_install_prereq.md

@@ -0,0 +1 @@
+Install and configure {{ app }}'s [app-preq].

content/includes/unit/howto_install_unit.md

@@ -0,0 +1 @@
+Install [Unit]({{< relref "/unit/installation.md#installation-precomp-pkgs" >}}) with a {{ mod }} language module.

content/includes/unit/howto_install_venv.md

@@ -0,0 +1,22 @@
+.. include:: ../include/replace.rst
+```
+
+Create a virtual environment to install {{ app }}'s [app-pip-link]:
+
+```console
+   $ cd :nxt_ph:`/path/to/app/ <Path to the application directory; use a real path in your configuration>`
+   $ :nxt_hint:`python3 --version <Make sure your virtual environment version matches the module version>`
+         Python :nxt_hint:`3.Y.Z <Major version, minor version, and revision number>`
+   $ python3 -m venv :nxt_hint:`venv <Arbitrary name of the virtual environment>`
+   $ source :nxt_hint:`venv <Name of the virtual environment from the previous command>`/bin/activate
+   $ pip install |app-pip-package|
+   $ deactivate
+```
+
+{{< warning >}}
+Create your virtual environment with a Python version that matches the
+language module from Step 1 up to the minor number (**3.Y** in this
+example). Also, the app **type** in Step 5 must {ref}`resolve
+<configuration-apps-common>` to a similarly matching version; Unit doesn't
+infer it from the environment.
+{{< /warning >}}

content/includes/unit/howto_upload_config.md

@@ -0,0 +1,14 @@
+Assuming the JSON above was added to
+`config.json`. Run the following command as root:
+
+```console
+# curl -X PUT --data-binary @config.json --unix-socket \
+   /path/to/control.unit.sock \  # Path to Unit's control socket in your installation
+   http://localhost/config/      # Path to the config section in Unit's control API
+```
+
+{{< note >}}
+The [control socket]({{< relref "/unit/installation.md#configuration-socket" >}}) path may vary; run
+`unitd -h` or see
+[Startup and shutdown]({{< relref "/unit/howto/source.md#source-startup" >}}) for details.
+{{< /note >}}

content/includes/unit/version.md

@@ -0,0 +1 @@
+1.34.1

content/unit/_index.md

@@ -0,0 +1,6 @@
+---
+title: NGINX Unit
+description: A lightweight web app server that combines several layers of the typical application stack into a single component.
+url: /nginx-unit/
+---
+

content/unit/about.md

@@ -0,0 +1,25 @@
+---
+title: About NGINX Unit
+weight: 100
+toc: true
+---
+
+# Universal web app server
+
+NGINX Unit is a lightweight and versatile application runtime that provides the
+essential components for your web application as a single open-source server:
+running application code (including WebAssembly), serving static assets,
+handling TLS and request routing.
+
+Unit was created by [nginx](https://nginx.org/en/) team members from scratch to
+be highly efficient and fully configurable at runtime. You can read the details
+about the latest release in the [news]({{< relref "/unit/news/">}}) section.
+
+- See a quickstart [guide](https://github.com/nginx/unit/) on our GitHub page.
+- Browse the [Changelog]({{< relref "/unit/changes/">}}) or see the release notes in the [Releases and announcements]({{< relref "/unit/news/">}}) archive.
+- Check out the discussion of our [key features]({{< relref "/unit/keyfeatures.md">}}) for further
+   details.
+- Peek at our future plans with a GitHub-based [roadmap](https://github.com/orgs/nginx/projects/1).
+
+
+Watch the entire NGINX Unit tutorial course in the [NGINX YouTube channel](https://www.youtube.com/playlist?list=PLGz_X9w9raXdV3vuPUu0kKBSBjG9rPaUf).

content/unit/certificates.md

@@ -0,0 +1,193 @@
+---
+title: SSL/TLS certificates
+weight: 800
+toc: true
+---
+
+The **/certificates** section of the [control API]({{< relref "/unit/controlapi.md" >}})
+handles TLS certificates that are used with Unit's
+[listeners]({{< relref "/unit/configuration.md#configuration-listeners">}}).
+To set up SSL/TLS for a listener, upload a **.pem** file with your certificate
+chain and private key to Unit, and name the uploaded bundle in the listener's configuration; next, the listener can be accessed via SSL/TLS.
+
+{{< note >}}
+For the details of certificate issuance and renewal in Unit,
+see an example in [TLS with Certbot]({{< relref "/unit/howto/certbot.md" >}}).
+{{< /note >}}
+
+
+First, create a **.pem** file with your certificate chain and private key:
+
+```console
+cat cert.pem ca.pem key.pem > bundle.pem  # Leaf certificate file | CA certificate file | Private key file | Arbitrary certificate bundle's filename
+```
+
+Usually, your website's certificate (optionally followed by the intermediate CA certificate) is enough to build a certificate chain. If you add more certificates
+to your chain, order them leaf to root.
+
+Upload the resulting bundle file to Unit's certificate storage under a suitable name
+(in this case, **bundle**), running the following command as root:
+
+```console
+# curl -X PUT --data-binary @bundle.pem --unix-socket /path/to/control.unit.sock http://localhost/certificates/bundle
+
+{
+    "success": "Certificate chain uploaded."
+}
+```
+
+{{< warning >}}
+Don't use **-d** for file upload with `curl`; this option damages **.pem** files.
+Use the **--data-binary** option when uploading file-based data to avoid data
+corruption.
+{{< /warning >}}
+
+Internally, Unit stores the uploaded certificate bundles along with other configuration data in its **state** subdirectory; the
+[control API]({{< relref "/unit/controlapi.md" >}})
+exposes some of their properties as **GET**-table JSON using **/certificates**:
+
+```json
+{
+    "certificates": {
+        "bundle": {
+            "key": "RSA (4096 bits)",
+            "chain": [
+                {
+                    "subject": {
+                        "common_name": "example.com",
+                        "alt_names": [
+                            "example.com",
+                            "www.example.com"
+                        ],
+
+                        "country": "US",
+                        "state_or_province": "CA",
+                        "organization": "Acme, Inc."
+                    },
+
+                    "issuer": {
+                        "common_name": "intermediate.ca.example.com",
+                        "country": "US",
+                        "state_or_province": "CA",
+                        "organization": "Acme Certification Authority"
+                    },
+
+                    "validity": {
+                        "since": "Sep 18 19:46:19 2022 GMT",
+                        "until": "Jun 15 19:46:19 2025 GMT"
+                    }
+                },
+                {
+                    "subject": {
+                        "common_name": "intermediate.ca.example.com",
+                        "country": "US",
+                        "state_or_province": "CA",
+                        "organization": "Acme Certification Authority"
+                    },
+
+                    "issuer": {
+                        "common_name": "root.ca.example.com",
+                        "country": "US",
+                        "state_or_province": "CA",
+                        "organization": "Acme Root Certification Authority"
+                    },
+
+                    "validity": {
+                        "since": "Feb 22 22:45:55 2023 GMT",
+                        "until": "Feb 21 22:45:55 2026 GMT"
+                    }
+                }
+            ]
+        }
+    }
+}
+```
+
+{{< note >}}
+Access array items, such as individual certificates in a chain,
+and their properties by indexing, running the following commands as root:
+
+```console
+# curl -X GET --unix-socket /path/to/control.unit.sock  # Path to Unit's control socket in your installation \
+       http://localhost/certificates/bundle/chain/0/    # Certificate bundle name
+```
+
+```console
+# curl -X GET --unix-socket /path/to/control.unit.sock  # Path to Unit's control socket in your installation \
+       http://localhost/certificates/bundle/chain/0/subject/alt_names/0/  # Certificate bundle name
+```
+{{< /note >}}
+
+Next, add the uploaded bundle to a
+[listener]({{< relref "/unit/configuration.md#configuration-listeners" >}}).
+the resulting control API configuration may look like this:
+
+```json
+{
+    "certificates": {
+        "bundle": {
+            "key": "<key type>",
+            "chain": [
+                "<certificate chain, omitted for brevity>"
+            ],
+            "comment_bundle": "Certificate bundle name"
+        }
+    },
+
+    "config": {
+        "listeners": {
+            "*:443": {
+                "pass": "applications/wsgi-app",
+                "tls": {
+                    "certificate": "bundle",
+                    "comment_certificate": "Certificate bundle name"
+                }
+            }
+        },
+
+        "applications": {
+            "wsgi-app": {
+                "type": "python",
+                "module": "wsgi",
+                "path": "/usr/www/wsgi-app/"
+            }
+        }
+    }
+}
+```
+
+All done;
+the application is now accessible via SSL/TLS:
+
+```console
+$ curl -v https://127.0.0.1 # Port 443 is conventionally used for HTTPS connections
+    ...
+    * TLSv1.2 (OUT), TLS handshake, Client hello (1):
+    * TLSv1.2 (IN), TLS handshake, Server hello (2):
+    * TLSv1.2 (IN), TLS handshake, Certificate (11):
+    * TLSv1.2 (IN), TLS handshake, Server finished (14):
+    * TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
+    * TLSv1.2 (OUT), TLS change cipher, Client hello (1):
+    * TLSv1.2 (OUT), TLS handshake, Finished (20):
+    * TLSv1.2 (IN), TLS change cipher, Client hello (1):
+    * TLSv1.2 (IN), TLS handshake, Finished (20):
+    * SSL connection using TLSv1.2 / AES256-GCM-SHA384
+    ...
+```
+
+Finally, you can delete a certificate bundle that you don't need anymore
+from the storage, running the following command as root:
+
+```console
+# curl -X DELETE --unix-socket /path/to/control.unit.sock  # Path to Unit's control socket in your installation \
+       http://localhost/certificates/bundle              # Certificate bundle name
+
+{
+    "success": "Certificate deleted."
+}
+```
+
+{{< note >}}
+You can't delete certificate bundles still referenced in your configuration,
+overwrite existing bundles using **put**, or delete non-existent ones.
+{{< /note >}}