diff options
Diffstat (limited to '')
| -rw-r--r-- | README.md | 145 |
1 files changed, 117 insertions, 28 deletions
@@ -1,5 +1,9 @@ # NGINX Unit +[](https://www.repostatus.org/#active) +[](https://github.com/nginx/unit/actions/workflows/ci.yml "GitHub workflow CI") +[](https://github.com/nginx/unit/discussions "GitHub Discussions") + ## Universal Web App Server  @@ -8,7 +12,7 @@ NGINX Unit is a lightweight and versatile open-source server that has two primary capabilities: - serves static media assets, -- runs application code in seven languages. +- runs application code in eight languages. Unit compresses several layers of the modern application stack into a potent, coherent solution with a focus on performance, low latency, and scalability. It @@ -22,11 +26,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 ``` @@ -34,47 +39,136 @@ $ brew install nginx/unit/unit For details and available language packages, see the [docs](https://unit.nginx.org/installation/#homebrew). - ### Docker ``` console -$ docker pull unit +$ docker pull unit:<TAG> +$ mkdir /tmp/unit-control # customize as needed. +$ docker run -d \ + --mount type=bind,src=/tmp/unit-control,dst=/var/run \ + --mount type=bind,src=.,dst=/www \ + --network host \ + unit ``` For a description of image tags, see the [docs](https://unit.nginx.org/installation/#docker-images). +WARNING: latest image tag may not provide support for specific language +modules, *do* check the available image tags from the link above before +pulling your image. + +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` + +[`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 -### Debian, Ubuntu +> [!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). +## 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. + +> [!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. -## Running a Hello World App +Here's an example using the `unit:python` Docker image: +``` console +$ unitctl instances new 127.0.0.1:8001 /path/to/app 'unit:python' +``` + +`/path/to/app` will mount to `/www` in the Docker filesystem. + +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 @@ -104,7 +198,6 @@ usually available by default via a Unix domain socket: /path/to/control.unit.sock http://localhost/config/applications ``` ``` json - { "success": "Reconfiguration done." } @@ -158,8 +251,10 @@ Unit's output should contain both snippets, neatly organized: } ``` -For full details of configuration management, see the -[docs](https://unit.nginx.org/configuration/#configuration-management). +## WebAssembly +Unit supports running WebAssembly Components (WASI 0.2). +For more information see the +[Unit Configuration Docs](https://unit.nginx.org/configuration/#configuration-wasm). ## OpenAPI Specification @@ -167,11 +262,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 @@ -192,7 +282,6 @@ usability. - To reach the team directly, subscribe to the [mailing list](https://mailman.nginx.org/mailman/listinfo/unit). -- For security issues, [email us](security-alert@nginx.org), mentioning - NGINX Unit in the subject and following the [CVSS +- For security issues, [email us](mailto:security-alert@nginx.org), + mentioning NGINX Unit in the subject and following the [CVSS v3.1](https://www.first.org/cvss/v3.1/specification-document) spec. - |