xref: /unit/README.md (revision 2184:3024bf4c5a39) 
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
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# apt install unit
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
74Suppose you saved a PHP script as `/www/helloworld/index.php`:
75``` php
76<?php echo "Hello, PHP on Unit!"; ?>
77```
78
79To run it on Unit with the `unit-php` module installed, first set up an
80application object. Let's store our first config snippet in a file called
81`config.json`:
82
83``` json
84{
85    "helloworld": {
86        "type": "php",
87        "root": "/www/helloworld/"
88    }
89}
90```
91
92Saving it as a file isn't necessary, but can come in handy with larger objects.
93
94Now, `PUT` it into the `config/applications` section of Unit's control API,
95usually available by default via a Unix domain socket:
96
97``` console
98# curl -X PUT --data-binary @config.json --unix-socket  \
99       /path/to/control.unit.sock http://localhost/config/applications
100```
101``` json
102
103{
104	"success": "Reconfiguration done."
105}
106```
107
108Next, reference the app from a listener object in the `config/listeners`
109section of the API.  This time, we pass the config snippet straight from the
110command line:
111
112``` console
113# curl -X PUT -d '{"127.0.0.1:8000": {"pass": "applications/helloworld"}}'  \
114       --unix-socket /path/to/control.unit.sock http://localhost/config/listeners
115```
116``` json
117{
118    "success": "Reconfiguration done."
119}
120```
121
122Now Unit accepts requests at the specified IP and port, passing them to the
123application process. Your app works!
124
125``` console
126$ curl 127.0.0.1:8080
127
128      Hello, PHP on Unit!
129```
130
131Finally, query the entire `/config` section of the control API:
132
133``` console
134# curl --unix-socket /path/to/control.unit.sock http://localhost/config/
135```
136
137Unit's output should contain both snippets, neatly organized:
138
139``` json
140{
141    "listeners": {
142        "127.0.0.1:8080": {
143            "pass": "applications/helloworld"
144        }
145    },
146
147    "applications": {
148        "helloworld": {
149            "type": "php",
150            "root": "/www/helloworld/"
151        }
152    }
153}
154```
155
156For full details of configuration management, see the
157[docs](https://unit.nginx.org/configuration/#configuration-management).
158
159
160## Community
161
162- The go-to place to start asking questions and share your thoughts is
163  our [Slack channel](https://nginxcommunity.slack.com/).
164
165- Our [GitHub issues page](https://github.com/nginx/unit/issues) offers
166  space for a more technical discussion at your own pace.
167
168- The [project map](https://github.com/orgs/nginx/projects/1) on
169  GitHub sheds some light on our current work and plans for the future.
170
171- Our [official website](https://unit.nginx.org/) may provide answers
172  not easily found otherwise.
173
174- Get involved with the project by contributing! See the
175  [contributing guide](CONTRIBUTING.md) for details.
176
177- To reach the team directly, subscribe to the
178  [mailing list](https://mailman.nginx.org/mailman/listinfo/unit).
179
180- For security issues, [email us](security-alert@nginx.org), mentioning
181  NGINX Unit in the subject and following the [CVSS
182  v3.1](https://www.first.org/cvss/v3.1/specification-document) spec.
183
184