12095Sartem.konev@nginx.com# NGINX Unit 22095Sartem.konev@nginx.com 32753Sa.clayton@nginx.com## Universal Web App Server 4*2754Sa.clayton@nginx.com 52753Sa.clayton@nginx.com![NGINX Unit Logo](docs/unitlogo.svg) 62095Sartem.konev@nginx.com 72095Sartem.konev@nginx.comNGINX Unit is a lightweight and versatile open-source server that has 82184Sartem.konev@nginx.comtwo primary capabilities: 92095Sartem.konev@nginx.com 102095Sartem.konev@nginx.com- serves static media assets, 112458Sartem.konev@nginx.com- runs application code in seven languages. 122095Sartem.konev@nginx.com 132306Sartem.konev@nginx.comUnit compresses several layers of the modern application stack into a potent, 142306Sartem.konev@nginx.comcoherent solution with a focus on performance, low latency, and scalability. It 152095Sartem.konev@nginx.comis intended as a universal building block for any web architecture regardless 162306Sartem.konev@nginx.comof its complexity, from enterprise-scale deployments to your pet's homepage. 172306Sartem.konev@nginx.com 182306Sartem.konev@nginx.comIts native [RESTful JSON API](#openapi-specification) enables dynamic 192306Sartem.konev@nginx.comupdates with zero interruptions and flexible configuration, while its 202095Sartem.konev@nginx.comout-of-the-box productivity reliably scales to production-grade workloads. We 212467Sartem.konev@nginx.comachieve that with a complex, asynchronous, multithreading architecture 222466Sartem.konev@nginx.comcomprising multiple processes to ensure security and robustness while getting 232466Sartem.konev@nginx.comthe most out of today's computing platforms. 242466Sartem.konev@nginx.com 252466Sartem.konev@nginx.com 262466Sartem.konev@nginx.com## Quick Installation 272095Sartem.konev@nginx.com 282095Sartem.konev@nginx.com### macOS 292095Sartem.konev@nginx.com 302095Sartem.konev@nginx.com``` console 312095Sartem.konev@nginx.com$ brew install nginx/unit/unit 322095Sartem.konev@nginx.com``` 332095Sartem.konev@nginx.com 342095Sartem.konev@nginx.comFor details and available language packages, see the 352095Sartem.konev@nginx.com[docs](https://unit.nginx.org/installation/#homebrew). 362095Sartem.konev@nginx.com 372095Sartem.konev@nginx.com 382095Sartem.konev@nginx.com### Docker 392095Sartem.konev@nginx.com 402095Sartem.konev@nginx.com``` console 412095Sartem.konev@nginx.com$ docker pull unit 422095Sartem.konev@nginx.com``` 432095Sartem.konev@nginx.com 442509S41629299+artemkonev@users.noreply.github.comFor a description of image tags, see the 452095Sartem.konev@nginx.com[docs](https://unit.nginx.org/installation/#docker-images). 462095Sartem.konev@nginx.com 472095Sartem.konev@nginx.com 482095Sartem.konev@nginx.com### Amazon Linux, Fedora, Red Hat 492095Sartem.konev@nginx.com 502095Sartem.konev@nginx.com``` console 512602Sa.clayton@nginx.com$ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit && chmod +x setup-unit 522095Sartem.konev@nginx.com# ./setup-unit repo-config && yum install unit 532095Sartem.konev@nginx.com# ./setup-unit welcome 542280Sartem.konev@nginx.com``` 552280Sartem.konev@nginx.com 562280Sartem.konev@nginx.comFor details and available language packages, see the 572095Sartem.konev@nginx.com[docs](https://unit.nginx.org/installation/#official-packages). 582095Sartem.konev@nginx.com 592095Sartem.konev@nginx.com 602095Sartem.konev@nginx.com### Debian, Ubuntu 612095Sartem.konev@nginx.com 622095Sartem.konev@nginx.com``` console 632095Sartem.konev@nginx.com$ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit && chmod +x setup-unit 642095Sartem.konev@nginx.com# ./setup-unit repo-config && apt install unit 652095Sartem.konev@nginx.com# ./setup-unit welcome 662280Sartem.konev@nginx.com``` 672280Sartem.konev@nginx.com 682280Sartem.konev@nginx.comFor details and available language packages, see the 692095Sartem.konev@nginx.com[docs](https://unit.nginx.org/installation/#official-packages). 702095Sartem.konev@nginx.com 712095Sartem.konev@nginx.com 722095Sartem.konev@nginx.com## Running a Hello World App 732095Sartem.konev@nginx.com 742095Sartem.konev@nginx.comUnit runs apps in a 752095Sartem.konev@nginx.com[variety of languages](https://unit.nginx.org/howto/samples/). 762095Sartem.konev@nginx.comLet's consider a basic example, 772509S41629299+artemkonev@users.noreply.github.comchoosing PHP for no particular reason. 782509S41629299+artemkonev@users.noreply.github.com 792509S41629299+artemkonev@users.noreply.github.comSuppose you saved a PHP script as `/www/helloworld/index.php`: 802509S41629299+artemkonev@users.noreply.github.com``` php 812509S41629299+artemkonev@users.noreply.github.com<?php echo "Hello, PHP on Unit!"; ?> 822095Sartem.konev@nginx.com``` 832095Sartem.konev@nginx.com 842095Sartem.konev@nginx.comTo run it on Unit with the `unit-php` module installed, first set up an 852095Sartem.konev@nginx.comapplication object. Let's store our first config snippet in a file called 862095Sartem.konev@nginx.com`config.json`: 872095Sartem.konev@nginx.com 882095Sartem.konev@nginx.com``` json 892095Sartem.konev@nginx.com{ 902095Sartem.konev@nginx.com "helloworld": { 912095Sartem.konev@nginx.com "type": "php", 922095Sartem.konev@nginx.com "root": "/www/helloworld/" 932095Sartem.konev@nginx.com } 942095Sartem.konev@nginx.com} 952095Sartem.konev@nginx.com``` 962095Sartem.konev@nginx.com 972095Sartem.konev@nginx.comSaving it as a file isn't necessary, but can come in handy with larger objects. 982095Sartem.konev@nginx.com 992095Sartem.konev@nginx.comNow, `PUT` it into the `/config/applications` section of Unit's control API, 1002095Sartem.konev@nginx.comusually available by default via a Unix domain socket: 1012095Sartem.konev@nginx.com 1022211Sartem.konev@nginx.com``` console 1032095Sartem.konev@nginx.com# curl -X PUT --data-binary @config.json --unix-socket \ 1042095Sartem.konev@nginx.com /path/to/control.unit.sock http://localhost/config/applications 1052095Sartem.konev@nginx.com``` 1062095Sartem.konev@nginx.com``` json 1072095Sartem.konev@nginx.com 1082095Sartem.konev@nginx.com{ 1092095Sartem.konev@nginx.com "success": "Reconfiguration done." 1102095Sartem.konev@nginx.com} 1112095Sartem.konev@nginx.com``` 1122095Sartem.konev@nginx.com 1132095Sartem.konev@nginx.comNext, reference the app from a listener object in the `/config/listeners` 1142095Sartem.konev@nginx.comsection of the API. This time, we pass the config snippet straight from the 1152095Sartem.konev@nginx.comcommand line: 1162211Sartem.konev@nginx.com 1172095Sartem.konev@nginx.com``` console 1182095Sartem.konev@nginx.com# curl -X PUT -d '{"127.0.0.1:8080": {"pass": "applications/helloworld"}}' \ 1192095Sartem.konev@nginx.com --unix-socket /path/to/control.unit.sock http://localhost/config/listeners 1202095Sartem.konev@nginx.com``` 1212603Schrisadams1267@gmail.com``` json 1222095Sartem.konev@nginx.com{ 1232095Sartem.konev@nginx.com "success": "Reconfiguration done." 1242095Sartem.konev@nginx.com} 1252095Sartem.konev@nginx.com``` 1262095Sartem.konev@nginx.com 1272095Sartem.konev@nginx.comNow Unit accepts requests at the specified IP and port, passing them to the 1282095Sartem.konev@nginx.comapplication process. Your app works! 1292095Sartem.konev@nginx.com 1302095Sartem.konev@nginx.com``` console 1312095Sartem.konev@nginx.com$ curl 127.0.0.1:8080 1322095Sartem.konev@nginx.com 1332095Sartem.konev@nginx.com Hello, PHP on Unit! 1342095Sartem.konev@nginx.com``` 1352095Sartem.konev@nginx.com 1362095Sartem.konev@nginx.comFinally, query the entire `/config` section of the control API: 1372095Sartem.konev@nginx.com 1382095Sartem.konev@nginx.com``` console 1392095Sartem.konev@nginx.com# curl --unix-socket /path/to/control.unit.sock http://localhost/config/ 1402095Sartem.konev@nginx.com``` 1412095Sartem.konev@nginx.com 1422095Sartem.konev@nginx.comUnit's output should contain both snippets, neatly organized: 1432095Sartem.konev@nginx.com 1442095Sartem.konev@nginx.com``` json 1452095Sartem.konev@nginx.com{ 1462095Sartem.konev@nginx.com "listeners": { 1472095Sartem.konev@nginx.com "127.0.0.1:8080": { 1482095Sartem.konev@nginx.com "pass": "applications/helloworld" 1492095Sartem.konev@nginx.com } 1502095Sartem.konev@nginx.com }, 1512095Sartem.konev@nginx.com 1522095Sartem.konev@nginx.com "applications": { 1532095Sartem.konev@nginx.com "helloworld": { 1542095Sartem.konev@nginx.com "type": "php", 1552095Sartem.konev@nginx.com "root": "/www/helloworld/" 1562095Sartem.konev@nginx.com } 1572095Sartem.konev@nginx.com } 1582095Sartem.konev@nginx.com} 1592095Sartem.konev@nginx.com``` 1602095Sartem.konev@nginx.com 1612095Sartem.konev@nginx.comFor full details of configuration management, see the 1622095Sartem.konev@nginx.com[docs](https://unit.nginx.org/configuration/#configuration-management). 1632095Sartem.konev@nginx.com 1642095Sartem.konev@nginx.com## OpenAPI Specification 1652095Sartem.konev@nginx.com 1662095Sartem.konev@nginx.comOur [OpenAPI specification](docs/unit-openapi.yaml) aims to simplify 1672466Sartem.konev@nginx.comconfiguring and integrating NGINX Unit deployments and provide an authoritative 1682466Sartem.konev@nginx.comsource of knowledge about the control API. 1692467Sartem.konev@nginx.com 1702467Sartem.konev@nginx.comAlthough the specification is still in the early beta stage, it is a promising 1712467Sartem.konev@nginx.comstep forward for the NGINX Unit community. While working on it, we kindly ask 1722466Sartem.konev@nginx.comyou to experiment and provide feedback to help improve its functionality and 1732466Sartem.konev@nginx.comusability. 1742466Sartem.konev@nginx.com 1752466Sartem.konev@nginx.com## Community 1762466Sartem.konev@nginx.com 1772095Sartem.konev@nginx.com- The go-to place to start asking questions and share your thoughts is 1782095Sartem.konev@nginx.com [GitHub Discussions](https://github.com/nginx/unit/discussions). 1792095Sartem.konev@nginx.com 1802095Sartem.konev@nginx.com- Our [GitHub issues page](https://github.com/nginx/unit/issues) offers 1812611S34845739+tarynmusgrave@users.noreply.github.com space for a more technical discussion at your own pace. 1822095Sartem.konev@nginx.com 1832095Sartem.konev@nginx.com- The [project map](https://github.com/orgs/nginx/projects/1) on 1842095Sartem.konev@nginx.com GitHub sheds some light on our current work and plans for the future. 1852095Sartem.konev@nginx.com 1862095Sartem.konev@nginx.com- Our [official website](https://unit.nginx.org/) may provide answers 1872095Sartem.konev@nginx.com not easily found otherwise. 1882095Sartem.konev@nginx.com 1892095Sartem.konev@nginx.com- Get involved with the project by contributing! See the 1902095Sartem.konev@nginx.com [contributing guide](CONTRIBUTING.md) for details. 1912095Sartem.konev@nginx.com 1922095Sartem.konev@nginx.com- To reach the team directly, subscribe to the 1932095Sartem.konev@nginx.com [mailing list](https://mailman.nginx.org/mailman/listinfo/unit). 1942095Sartem.konev@nginx.com 1952095Sartem.konev@nginx.com- For security issues, [email us](security-alert@nginx.org), mentioning 1962095Sartem.konev@nginx.com NGINX Unit in the subject and following the [CVSS 1972095Sartem.konev@nginx.com v3.1](https://www.first.org/cvss/v3.1/specification-document) spec. 1982750Sa.clayton@nginx.com 1992750Sa.clayton@nginx.com