xref: /unit/README.md (revision 2211:0fdd0b751538)
12095Sartem.konev@nginx.com# NGINX Unit
22095Sartem.konev@nginx.com
32095Sartem.konev@nginx.com## Universal Web App Server
42095Sartem.konev@nginx.com
52184Sartem.konev@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
82095Sartem.konev@nginx.comthree core capabilities:
92095Sartem.konev@nginx.com
102095Sartem.konev@nginx.com- it is an HTTP reverse proxy,
112095Sartem.konev@nginx.com- a web server for static media assets,
122095Sartem.konev@nginx.com- and an application server that runs code in seven languages.
132095Sartem.konev@nginx.com
142095Sartem.konev@nginx.comWe are building a universal tool that compresses several layers of the modern
152095Sartem.konev@nginx.comapplication stack into a potent, coherent solution with a focus on performance,
162095Sartem.konev@nginx.comlow latency, and scalability. It is intended as a building block for any web
172095Sartem.konev@nginx.comarchitecture regardless of its complexity, from enterprise-scale deployments to
182095Sartem.konev@nginx.comyour pet's homepage.
192095Sartem.konev@nginx.com
202095Sartem.konev@nginx.comUnit's native RESTful JSON API enables dynamic updates with zero interruptions
212095Sartem.konev@nginx.comand flexible configuration, while its out-of-the-box productivity reliably
222095Sartem.konev@nginx.comscales to production-grade workloads. We achieve that with a complex,
232095Sartem.konev@nginx.comasynchronous, multithreading architecture comprising multiple processes to
242095Sartem.konev@nginx.comensure security and robustness while getting the most out of today's computing
252095Sartem.konev@nginx.complatforms.
262095Sartem.konev@nginx.com
272095Sartem.konev@nginx.com
282095Sartem.konev@nginx.com## Quick Installation
292095Sartem.konev@nginx.com
302095Sartem.konev@nginx.com### macOS
312095Sartem.konev@nginx.com
322095Sartem.konev@nginx.com``` console
332095Sartem.konev@nginx.com$ brew install nginx/unit/unit
342095Sartem.konev@nginx.com```
352095Sartem.konev@nginx.com
362095Sartem.konev@nginx.comFor details and available language packages, see the
372095Sartem.konev@nginx.com[docs](https://unit.nginx.org/installation/#homebrew).
382095Sartem.konev@nginx.com
392095Sartem.konev@nginx.com
402095Sartem.konev@nginx.com### Docker
412095Sartem.konev@nginx.com
422095Sartem.konev@nginx.com``` console
432095Sartem.konev@nginx.com$ docker pull docker.io/nginx/unit
442095Sartem.konev@nginx.com```
452095Sartem.konev@nginx.com
462095Sartem.konev@nginx.comFor a description of image tags, see the
472095Sartem.konev@nginx.com[docs](https://unit.nginx.org/installation/#docker-images).
482095Sartem.konev@nginx.com
492095Sartem.konev@nginx.com
502095Sartem.konev@nginx.com### Amazon Linux, Fedora, RedHat
512095Sartem.konev@nginx.com
522095Sartem.konev@nginx.com``` console
532095Sartem.konev@nginx.com$ curl -sL 'https://unit.nginx.org/_downloads/setup-unit.sh' | sudo -E bash
542095Sartem.konev@nginx.com# yum install unit
552095Sartem.konev@nginx.com```
562095Sartem.konev@nginx.com
572095Sartem.konev@nginx.comFor details and available language packages, see the
582095Sartem.konev@nginx.com[docs](https://unit.nginx.org/installation/#official-packages).
592095Sartem.konev@nginx.com
602095Sartem.konev@nginx.com
612095Sartem.konev@nginx.com### Debian, Ubuntu
622095Sartem.konev@nginx.com
632095Sartem.konev@nginx.com``` console
642095Sartem.konev@nginx.com$ curl -sL 'https://unit.nginx.org/_downloads/setup-unit.sh' | sudo -E bash
652095Sartem.konev@nginx.com# apt install unit
662095Sartem.konev@nginx.com```
672095Sartem.konev@nginx.com
682095Sartem.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.comSuppose you saved a PHP script as `/www/helloworld/index.php`:
752095Sartem.konev@nginx.com``` php
762095Sartem.konev@nginx.com<?php echo "Hello, PHP on Unit!"; ?>
772095Sartem.konev@nginx.com```
782095Sartem.konev@nginx.com
792095Sartem.konev@nginx.comTo run it on Unit with the `unit-php` module installed, first set up an
802095Sartem.konev@nginx.comapplication object. Let's store our first config snippet in a file called
812095Sartem.konev@nginx.com`config.json`:
822095Sartem.konev@nginx.com
832095Sartem.konev@nginx.com``` json
842095Sartem.konev@nginx.com{
852095Sartem.konev@nginx.com    "helloworld": {
862095Sartem.konev@nginx.com        "type": "php",
872095Sartem.konev@nginx.com        "root": "/www/helloworld/"
882095Sartem.konev@nginx.com    }
892095Sartem.konev@nginx.com}
902095Sartem.konev@nginx.com```
912095Sartem.konev@nginx.com
922095Sartem.konev@nginx.comSaving it as a file isn't necessary, but can come in handy with larger objects.
932095Sartem.konev@nginx.com
94*2211Sartem.konev@nginx.comNow, `PUT` it into the `/config/applications` section of Unit's control API,
952095Sartem.konev@nginx.comusually available by default via a Unix domain socket:
962095Sartem.konev@nginx.com
972095Sartem.konev@nginx.com``` console
982095Sartem.konev@nginx.com# curl -X PUT --data-binary @config.json --unix-socket  \
992095Sartem.konev@nginx.com       /path/to/control.unit.sock http://localhost/config/applications
1002095Sartem.konev@nginx.com```
1012095Sartem.konev@nginx.com``` json
1022095Sartem.konev@nginx.com
1032095Sartem.konev@nginx.com{
1042095Sartem.konev@nginx.com	"success": "Reconfiguration done."
1052095Sartem.konev@nginx.com}
1062095Sartem.konev@nginx.com```
1072095Sartem.konev@nginx.com
108*2211Sartem.konev@nginx.comNext, reference the app from a listener object in the `/config/listeners`
1092095Sartem.konev@nginx.comsection of the API.  This time, we pass the config snippet straight from the
1102095Sartem.konev@nginx.comcommand line:
1112095Sartem.konev@nginx.com
1122095Sartem.konev@nginx.com``` console
1132095Sartem.konev@nginx.com# curl -X PUT -d '{"127.0.0.1:8000": {"pass": "applications/helloworld"}}'  \
1142095Sartem.konev@nginx.com       --unix-socket /path/to/control.unit.sock http://localhost/config/listeners
1152095Sartem.konev@nginx.com```
1162095Sartem.konev@nginx.com``` json
1172095Sartem.konev@nginx.com{
1182095Sartem.konev@nginx.com    "success": "Reconfiguration done."
1192095Sartem.konev@nginx.com}
1202095Sartem.konev@nginx.com```
1212095Sartem.konev@nginx.com
1222095Sartem.konev@nginx.comNow Unit accepts requests at the specified IP and port, passing them to the
1232095Sartem.konev@nginx.comapplication process. Your app works!
1242095Sartem.konev@nginx.com
1252095Sartem.konev@nginx.com``` console
1262095Sartem.konev@nginx.com$ curl 127.0.0.1:8080
1272095Sartem.konev@nginx.com
1282095Sartem.konev@nginx.com      Hello, PHP on Unit!
1292095Sartem.konev@nginx.com```
1302095Sartem.konev@nginx.com
1312095Sartem.konev@nginx.comFinally, query the entire `/config` section of the control API:
1322095Sartem.konev@nginx.com
1332095Sartem.konev@nginx.com``` console
1342095Sartem.konev@nginx.com# curl --unix-socket /path/to/control.unit.sock http://localhost/config/
1352095Sartem.konev@nginx.com```
1362095Sartem.konev@nginx.com
1372095Sartem.konev@nginx.comUnit's output should contain both snippets, neatly organized:
1382095Sartem.konev@nginx.com
1392095Sartem.konev@nginx.com``` json
1402095Sartem.konev@nginx.com{
1412095Sartem.konev@nginx.com    "listeners": {
1422095Sartem.konev@nginx.com        "127.0.0.1:8080": {
1432095Sartem.konev@nginx.com            "pass": "applications/helloworld"
1442095Sartem.konev@nginx.com        }
1452095Sartem.konev@nginx.com    },
1462095Sartem.konev@nginx.com
1472095Sartem.konev@nginx.com    "applications": {
1482095Sartem.konev@nginx.com        "helloworld": {
1492095Sartem.konev@nginx.com            "type": "php",
1502095Sartem.konev@nginx.com            "root": "/www/helloworld/"
1512095Sartem.konev@nginx.com        }
1522095Sartem.konev@nginx.com    }
1532095Sartem.konev@nginx.com}
1542095Sartem.konev@nginx.com```
1552095Sartem.konev@nginx.com
1562095Sartem.konev@nginx.comFor full details of configuration management, see the
1572095Sartem.konev@nginx.com[docs](https://unit.nginx.org/configuration/#configuration-management).
1582095Sartem.konev@nginx.com
1592095Sartem.konev@nginx.com
1602095Sartem.konev@nginx.com## Community
1612095Sartem.konev@nginx.com
1622095Sartem.konev@nginx.com- The go-to place to start asking questions and share your thoughts is
1632095Sartem.konev@nginx.com  our [Slack channel](https://nginxcommunity.slack.com/).
1642095Sartem.konev@nginx.com
1652095Sartem.konev@nginx.com- Our [GitHub issues page](https://github.com/nginx/unit/issues) offers
1662095Sartem.konev@nginx.com  space for a more technical discussion at your own pace.
1672095Sartem.konev@nginx.com
1682095Sartem.konev@nginx.com- The [project map](https://github.com/orgs/nginx/projects/1) on
1692095Sartem.konev@nginx.com  GitHub sheds some light on our current work and plans for the future.
1702095Sartem.konev@nginx.com
1712095Sartem.konev@nginx.com- Our [official website](https://unit.nginx.org/) may provide answers
1722095Sartem.konev@nginx.com  not easily found otherwise.
1732095Sartem.konev@nginx.com
1742095Sartem.konev@nginx.com- Get involved with the project by contributing! See the
1752095Sartem.konev@nginx.com  [contributing guide](CONTRIBUTING.md) for details.
1762095Sartem.konev@nginx.com
1772095Sartem.konev@nginx.com- To reach the team directly, subscribe to the
1782095Sartem.konev@nginx.com  [mailing list](https://mailman.nginx.org/mailman/listinfo/unit).
1792095Sartem.konev@nginx.com
1802095Sartem.konev@nginx.com- For security issues, [email us](security-alert@nginx.org), mentioning
1812095Sartem.konev@nginx.com  NGINX Unit in the subject and following the [CVSS
1822095Sartem.konev@nginx.com  v3.1](https://www.first.org/cvss/v3.1/specification-document) spec.
1832095Sartem.konev@nginx.com
184