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