1# NGINX Unit 2 3## Universal Web App Server 4 5![NGINX Unit Logo](docs/unitlogo.svg) 6 7NGINX Unit is a lightweight and versatile open-source server that has 8two primary capabilities: 9 10- serves static media assets, 11- runs application code in seven languages. 12 13Unit compresses several layers of the modern application stack into a potent, 14coherent solution with a focus on performance, low latency, and scalability. It 15is intended as a universal building block for any web architecture regardless 16of its complexity, from enterprise-scale deployments to your pet's homepage. 17 18Its native [RESTful JSON API](#openapi-specification) enables dynamic 19updates with zero interruptions and flexible configuration, while its 20out-of-the-box productivity reliably scales to production-grade workloads. We 21achieve that with a complex, asynchronous, multithreading architecture 22comprising multiple processes to ensure security and robustness while getting 23the most out of today's computing platforms. 24 25 26## Quick Installation 27 28### macOS 29 30``` console 31$ brew install nginx/unit/unit 32``` 33 34For details and available language packages, see the 35[docs](https://unit.nginx.org/installation/#homebrew). 36 37 38### Docker 39 40``` console 41$ docker pull unit 42``` 43 44For a description of image tags, see the 45[docs](https://unit.nginx.org/installation/#docker-images). 46 47 48### Amazon Linux, Fedora, Red Hat 49 50``` console 51$ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit && chmod +x setup-unit 52# ./setup-unit repo-config && yum install unit 53# ./setup-unit welcome 54``` 55 56For details and available language packages, see the 57[docs](https://unit.nginx.org/installation/#official-packages). 58 59 60### Debian, Ubuntu 61 62``` console 63$ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit && chmod +x setup-unit 64# ./setup-unit repo-config && apt install unit 65# ./setup-unit welcome 66``` 67 68For details and available language packages, see the 69[docs](https://unit.nginx.org/installation/#official-packages). 70 71 72## Running a Hello World App 73 74Unit runs apps in a 75[variety of languages](https://unit.nginx.org/howto/samples/). 76Let's consider a basic example, 77choosing PHP for no particular reason. 78 79Suppose you saved a PHP script as `/www/helloworld/index.php`: 80``` php 81<?php echo "Hello, PHP on Unit!"; ?> 82``` 83 84To run it on Unit with the `unit-php` module installed, first set up an 85application object. Let's store our first config snippet in a file called 86`config.json`: 87 88``` json 89{ 90 "helloworld": { 91 "type": "php", 92 "root": "/www/helloworld/" 93 } 94} 95``` 96 97Saving it as a file isn't necessary, but can come in handy with larger objects. 98 99Now, `PUT` it into the `/config/applications` section of Unit's control API, 100usually available by default via a Unix domain socket: 101 102``` console 103# curl -X PUT --data-binary @config.json --unix-socket \ 104 /path/to/control.unit.sock http://localhost/config/applications 105``` 106``` json 107 108{ 109 "success": "Reconfiguration done." 110} 111``` 112 113Next, reference the app from a listener object in the `/config/listeners` 114section of the API. This time, we pass the config snippet straight from the 115command line: 116 117``` console 118# curl -X PUT -d '{"127.0.0.1:8080": {"pass": "applications/helloworld"}}' \ 119 --unix-socket /path/to/control.unit.sock http://localhost/config/listeners 120``` 121``` json 122{ 123 "success": "Reconfiguration done." 124} 125``` 126 127Now Unit accepts requests at the specified IP and port, passing them to the 128application process. Your app works! 129 130``` console 131$ curl 127.0.0.1:8080 132 133 Hello, PHP on Unit! 134``` 135 136Finally, query the entire `/config` section of the control API: 137 138``` console 139# curl --unix-socket /path/to/control.unit.sock http://localhost/config/ 140``` 141 142Unit's output should contain both snippets, neatly organized: 143 144``` json 145{ 146 "listeners": { 147 "127.0.0.1:8080": { 148 "pass": "applications/helloworld" 149 } 150 }, 151 152 "applications": { 153 "helloworld": { 154 "type": "php", 155 "root": "/www/helloworld/" 156 } 157 } 158} 159``` 160 161For full details of configuration management, see the 162[docs](https://unit.nginx.org/configuration/#configuration-management). 163 164## OpenAPI Specification 165 166Our [OpenAPI specification](docs/unit-openapi.yaml) aims to simplify 167configuring and integrating NGINX Unit deployments and provide an authoritative 168source of knowledge about the control API. 169 170Although the specification is still in the early beta stage, it is a promising 171step forward for the NGINX Unit community. While working on it, we kindly ask 172you to experiment and provide feedback to help improve its functionality and 173usability. 174 175## Community 176 177- The go-to place to start asking questions and share your thoughts is 178 [GitHub Discussions](https://github.com/nginx/unit/discussions). 179 180- Our [GitHub issues page](https://github.com/nginx/unit/issues) offers 181 space for a more technical discussion at your own pace. 182 183- The [project map](https://github.com/orgs/nginx/projects/1) on 184 GitHub sheds some light on our current work and plans for the future. 185 186- Our [official website](https://unit.nginx.org/) may provide answers 187 not easily found otherwise. 188 189- Get involved with the project by contributing! See the 190 [contributing guide](CONTRIBUTING.md) for details. 191 192- To reach the team directly, subscribe to the 193 [mailing list](https://mailman.nginx.org/mailman/listinfo/unit). 194 195- For security issues, [email us](security-alert@nginx.org), mentioning 196 NGINX Unit in the subject and following the [CVSS 197 v3.1](https://www.first.org/cvss/v3.1/specification-document) spec. 198 199