README.md
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# 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