xref: /unit/
Name Date Size #Lines LOC

..20-Dec-2020-

.github/workflows/H22-Feb-2024-

auto/H22-Feb-2024-

docs/H28-Feb-2024-

go/H11-Jan-2024-

pkg/H17-Feb-2024-

src/H22-Feb-2024-

test/H22-Feb-2024-

tools/H21-Feb-2024-

.gitattributesH A D17-Feb-2024118 86

.gitignoreH A D04-May-202236 54

.mailmapH A D22-Feb-20241.2 KiB2120

.rustfmt.tomlH A D22-Feb-202415 21

CHANGESH A D28-Feb-202437.4 KiB1,127661

CODE_OF_CONDUCT.mdH A D08-Mar-20233.3 KiB7556

CONTRIBUTING.mdH A D11-Jan-20243.2 KiB9159

LICENSEH A D20-Dec-20209.9 KiB179150

NOTICEH A D21-Feb-20241.3 KiB3831

README.mdH A D11-Jan-20245.4 KiB199142

SECURITY.txtH A D12-Jan-20241.1 KiB3127

configureH A D22-Aug-20233.4 KiB183122

versionH A D28-Feb-202466 63

README.md

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
8two primary capabilities:
9
10- serves static media assets,
11- runs application code in seven languages.
12
13Unit compresses several layers of the modern application stack into a potent,
14coherent solution with a focus on performance, low latency, and scalability. It
15is intended as a universal building block for any web architecture regardless
16of its complexity, from enterprise-scale deployments to your pet's homepage.
17
18Its native [RESTful JSON API](#openapi-specification) enables dynamic
19updates with zero interruptions and flexible configuration, while its
20out-of-the-box productivity reliably scales to production-grade workloads. We
21achieve that with a complex, asynchronous, multithreading architecture
22comprising multiple processes to ensure security and robustness while getting
23the most out of today's computing platforms.
24
25
26## Quick Installation
27
28### macOS
29
30``` console
31$ brew install nginx/unit/unit
32```
33
34For details and available language packages, see the
35[docs](https://unit.nginx.org/installation/#homebrew).
36
37
38### Docker
39
40``` console
41$ docker pull unit
42```
43
44For a description of image tags, see the
45[docs](https://unit.nginx.org/installation/#docker-images).
46
47
48### Amazon Linux, Fedora, Red Hat
49
50``` console
51$ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit && chmod +x setup-unit
52# ./setup-unit repo-config && yum install unit
53# ./setup-unit welcome
54```
55
56For details and available language packages, see the
57[docs](https://unit.nginx.org/installation/#official-packages).
58
59
60### Debian, Ubuntu
61
62``` console
63$ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit && chmod +x setup-unit
64# ./setup-unit repo-config && apt install unit
65# ./setup-unit welcome
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
74Unit runs apps in a
75[variety of languages](https://unit.nginx.org/howto/samples/).
76Let's consider a basic example,
77choosing PHP for no particular reason.
78
79Suppose you saved a PHP script as `/www/helloworld/index.php`:
80``` php
81<?php echo "Hello, PHP on Unit!"; ?>
82```
83
84To run it on Unit with the `unit-php` module installed, first set up an
85application object. Let's store our first config snippet in a file called
86`config.json`:
87
88``` json
89{
90    "helloworld": {
91        "type": "php",
92        "root": "/www/helloworld/"
93    }
94}
95```
96
97Saving it as a file isn't necessary, but can come in handy with larger objects.
98
99Now, `PUT` it into the `/config/applications` section of Unit's control API,
100usually available by default via a Unix domain socket:
101
102``` console
103# curl -X PUT --data-binary @config.json --unix-socket  \
104       /path/to/control.unit.sock http://localhost/config/applications
105```
106``` json
107
108{
109	"success": "Reconfiguration done."
110}
111```
112
113Next, reference the app from a listener object in the `/config/listeners`
114section of the API.  This time, we pass the config snippet straight from the
115command line:
116
117``` console
118# curl -X PUT -d '{"127.0.0.1:8080": {"pass": "applications/helloworld"}}'  \
119       --unix-socket /path/to/control.unit.sock http://localhost/config/listeners
120```
121``` json
122{
123    "success": "Reconfiguration done."
124}
125```
126
127Now Unit accepts requests at the specified IP and port, passing them to the
128application process. Your app works!
129
130``` console
131$ curl 127.0.0.1:8080
132
133      Hello, PHP on Unit!
134```
135
136Finally, query the entire `/config` section of the control API:
137
138``` console
139# curl --unix-socket /path/to/control.unit.sock http://localhost/config/
140```
141
142Unit's output should contain both snippets, neatly organized:
143
144``` json
145{
146    "listeners": {
147        "127.0.0.1:8080": {
148            "pass": "applications/helloworld"
149        }
150    },
151
152    "applications": {
153        "helloworld": {
154            "type": "php",
155            "root": "/www/helloworld/"
156        }
157    }
158}
159```
160
161For full details of configuration management, see the
162[docs](https://unit.nginx.org/configuration/#configuration-management).
163
164## OpenAPI Specification
165
166Our [OpenAPI specification](docs/unit-openapi.yaml) aims to simplify
167configuring and integrating NGINX Unit deployments and provide an authoritative
168source of knowledge about the control API.
169
170Although the specification is still in the early beta stage, it is a promising
171step forward for the NGINX Unit community. While working on it, we kindly ask
172you to experiment and provide feedback to help improve its functionality and
173usability.
174
175## Community
176
177- The go-to place to start asking questions and share your thoughts is
178 [GitHub Discussions](https://github.com/nginx/unit/discussions).
179
180- Our [GitHub issues page](https://github.com/nginx/unit/issues) offers
181  space for a more technical discussion at your own pace.
182
183- The [project map](https://github.com/orgs/nginx/projects/1) on
184  GitHub sheds some light on our current work and plans for the future.
185
186- Our [official website](https://unit.nginx.org/) may provide answers
187  not easily found otherwise.
188
189- Get involved with the project by contributing! See the
190  [contributing guide](CONTRIBUTING.md) for details.
191
192- To reach the team directly, subscribe to the
193  [mailing list](https://mailman.nginx.org/mailman/listinfo/unit).
194
195- For security issues, [email us](security-alert@nginx.org), mentioning
196  NGINX Unit in the subject and following the [CVSS
197  v3.1](https://www.first.org/cvss/v3.1/specification-document) spec.
198
199