diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 116 |
1 files changed, 89 insertions, 27 deletions
@@ -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 |