xref: /unit/README.md (revision 2754:f7847eeb8ccb)
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