From c30c2f5e4218d8931b64d5e3d1cdabd9690e7720 Mon Sep 17 00:00:00 2001
From: Danielle De Leo <d.deleo@f5.com>
Date: Wed, 15 May 2024 17:58:50 -0400
Subject: Add unitctl quickstart to README.md

---
 README.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 89 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index 0b322ffe..56daa4fc 100644
--- a/README.md
+++ b/README.md
@@ -25,11 +25,12 @@ achieve that with a complex, asynchronous, multithreading architecture
 comprising multiple processes to ensure security and robustness while getting
 the most out of today's computing platforms.
 
-
-## Quick Installation
+## Installation
 
 ### macOS
 
+Run the following command to install both `unitd` (the Unit daemon) and `unitctl` (the control tool).
+
 ``` console
 $ brew install nginx/unit/unit
 ```
@@ -37,7 +38,6 @@ $ brew install nginx/unit/unit
 For details and available language packages, see the
 [docs](https://unit.nginx.org/installation/#homebrew).
 
-
 ### Docker
 
 ``` console
@@ -61,45 +61,113 @@ Your current working directory will now be mounted to the Unit image at `/www`.
 You can reach its socket at `/tmp/unit-control/control.unit.sock` assuming no
 further customizations have been made.
 
-### Amazon Linux, Fedora, Red Hat
+### Debian, Ubuntu, Amazon Linux, Fedora, Red Hat
 
+This helper script configures the correct package repositories for system.
 ``` console
 $ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit && chmod +x setup-unit
-# ./setup-unit repo-config && yum install unit
-# ./setup-unit welcome
+# ./setup-unit repo-config
+```
+
+Debian derivatives:
+``` console
+# apt install unit
+```
+
+Fedora derivatives:
+``` console
+# yum install unit
 ```
 
 For details and available language packages, see the
 [docs](https://unit.nginx.org/installation/#official-packages).
 
+## Getting Started with `unitctl`
 
-### Debian, Ubuntu
+[`unitctl`](tools/README.md) streamlines the management of NGINX Unit processes
+through an easy-to-use command line interface. To get started with `unitctl`,
+download it from the
+[official GitHub releases](https://github.com/nginx/unit/releases)
+or [Homebrew](#macos).
+
+### Installation
+
+> [!NOTE]
+> If you installed Unit with [Homebrew](#macos), you can skip this step
+> as `unitctl` is included by default.
+
+Download the appropriate `unitctl` binary for your system from the
+[NGINX Unit releases](https://github.com/nginx/unit/releases/).
 
 ``` console
-$ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit && chmod +x setup-unit
-# ./setup-unit repo-config && apt install unit
-# ./setup-unit welcome
+$ tar xzvf unitctl-master-x86_64-unknown-linux-gnu.tar.gz
+# mv unitctl /usr/local/bin/
 ```
 
-For details and available language packages, see the
-[docs](https://unit.nginx.org/installation/#official-packages).
 
-## Configuration
+## Launch Unit using Docker
+If you have [Docker installed](https://docs.docker.com/engine/install/) on
+your machine, and then you can effortlessly spin up one of
+[Unit's official Docker images](https://hub.docker.com/_/unit)
+alongside your application.
 
-NGINX Unit provides a RESTful API for dynamic configuration.
-See the [control API documentation](https://unit.nginx.org/controlapi/)
-for more information on what endpoints are available and how to use them.
+> [!TIP]
+> How-to and configuration guides are available on
+[unit.nginx.org](https://unit.nginx.org/howto/) for web application frameworks
+built with Python, PHP, WebAssembly, Node.js, Ruby, and more.
 
+Here's an example using the `unit:python` Docker image:
+``` console
+$ unitctl instances new 127.0.0.1:8001 /path/to/app 'unit:python'
+```
 
-For full details of configuration management, see the
-[docs](https://unit.nginx.org/configuration/#configuration-management).
+`/path/to/app` will mount to `/www` in the Docker filesystem.
 
-## Running a Hello World App
+Save this to `/path/to/app/wsgi.py`:
+```python
+def application(environ, start_response):
+    start_response("200 OK", [("Content-Type", "text/plain")])
+    return (b"Hello, Python on Unit!")
+```
+
+You can then interactively edit the currently active configuration:
+``` console
+$ unitctl edit
+```
+```jsonc
+{
+  "listeners": {
+    "*:8000": {
+      // Point listener to new application
+      "pass": "applications/python"
+    }
+  },
+
+  // Add an application definition
+  "applications": {
+    "python": {
+        "type": "python",
+        "path": "/www/",
+        "module": "wsgi"
+    }
+  }
+}
+```
+Valid configurations will be applied upon save and close.
+
+``` console
+$ curl localhost:8000
+
+Hello, Python on Unit!
+```
+More Python configuration examples can be found in the
+[Unit docs](https://unit.nginx.org/howto/samples/#python).
+
+## Hello World with PHP and curl
 
 Unit runs apps in a
 [variety of languages](https://unit.nginx.org/howto/samples/).
-Let's consider a basic example,
-choosing PHP for no particular reason.
+Let's explore the configuration of a simple PHP app on Unit with `curl`.
 
 Suppose you saved a PHP script as `/www/helloworld/index.php`:
 ``` php
@@ -129,7 +197,6 @@ usually available by default via a Unix domain socket:
        /path/to/control.unit.sock http://localhost/config/applications
 ```
 ``` json
-
 {
 	"success": "Reconfiguration done."
 }
@@ -194,11 +261,6 @@ Our [OpenAPI specification](docs/unit-openapi.yaml) aims to simplify
 configuring and integrating NGINX Unit deployments and provide an authoritative
 source of knowledge about the control API.
 
-Although the specification is still in the early beta stage, it is a promising
-step forward for the NGINX Unit community. While working on it, we kindly ask
-you to experiment and provide feedback to help improve its functionality and
-usability.
-
 ## Community
 
 - The go-to place to start asking questions and share your thoughts is
-- 
cgit