Adding GitHub-styled README and CONTRIBUTING files in Markdown.
This commit is contained in:
parent
de0a0beb83
commit
fa42d858a2
4 changed files with 274 additions and 24 deletions
90
CONTRIBUTING.md
Normal file
90
CONTRIBUTING.md
Normal file
|
@ -0,0 +1,90 @@
|
|||
# Contributing Guidelines
|
||||
|
||||
The following is a set of guidelines for contributing to NGINX Unit. We do
|
||||
appreciate that you are considering contributing!
|
||||
|
||||
## Table Of Contents
|
||||
|
||||
- [Getting Started](#getting-started)
|
||||
- [Ask a Question](#ask-a-question)
|
||||
- [Contributing](#contributing)
|
||||
- [Git Style Guide](#git-style-guide)
|
||||
|
||||
|
||||
## Getting Started
|
||||
|
||||
Check out the [Quick Installation](README.md#quick-installation) and
|
||||
[Howto](https://unit.nginx.org/howto/) guides to get NGINX Unit up and running.
|
||||
|
||||
|
||||
## Ask a Question
|
||||
|
||||
Please open an [issue](https://github.com/nginx/unit/issues/new) on GitHub with
|
||||
the label `question`. You can also ask a question on
|
||||
[Slack](https://nginxcommunity.slack.com) or the NGINX Unit mailing list,
|
||||
unit@nginx.org (subscribe
|
||||
[here](https://mailman.nginx.org/mailman3/lists/unit.nginx.org/)).
|
||||
|
||||
|
||||
## Contributing
|
||||
|
||||
### Report a Bug
|
||||
|
||||
Ensure the bug was not already reported by searching on GitHub under
|
||||
[Issues](https://github.com/nginx/unit/issues).
|
||||
|
||||
If the bug is a potential security vulnerability, please report using our
|
||||
[security policy](https://unit.nginx.org/troubleshooting/#getting-support).
|
||||
|
||||
To report a non-security bug, open an
|
||||
[issue](https://github.com/nginx/unit/issues/new) on GitHub with the label
|
||||
`bug`. Be sure to include a title and clear description, as much relevant
|
||||
information as possible, and a code sample or an executable test case showing
|
||||
the expected behavior that doesn't occur.
|
||||
|
||||
|
||||
### Suggest an Enhancement
|
||||
|
||||
To suggest an enhancement, open an
|
||||
[issue](https://github.com/nginx/unit/issues/new) on GitHub with the label
|
||||
`enhancement`. Please do this before implementing a new feature to discuss the
|
||||
feature first.
|
||||
|
||||
|
||||
### Open a Pull Request
|
||||
|
||||
Before submitting a PR, please read the NGINX Unit code guidelines to know more
|
||||
about coding conventions and benchmarks. Fork the repo, create a branch, and
|
||||
submit a PR when your changes are tested and ready for review. Again, if you'd
|
||||
like to implement a new feature, please consider creating a feature request
|
||||
issue first to start a discussion about the feature.
|
||||
|
||||
|
||||
## Git Style Guide
|
||||
|
||||
- Keep a clean, concise and meaningful `git commit` history on your branch,
|
||||
rebasing locally and squashing before submitting a PR
|
||||
|
||||
- For any user-visible changes, updates, and bugfixes, add a note to
|
||||
`docs/changes.xml` under the section for the upcoming release, using `<change
|
||||
type="feature">` for new functionality, `<change type="change">` for changed
|
||||
behavior, and `<change type="bugfix">` for bug fixes.
|
||||
|
||||
- In the subject line, use the past tense ("Added feature", not "Add feature");
|
||||
also, use past tense to describe past scenarios, and present tense for
|
||||
current behavior
|
||||
|
||||
- Limit the subject line to 67 characters, and the rest of the commit message
|
||||
to 80 characters
|
||||
|
||||
- Use subject line prefixes for commits that affect a specific portion of the
|
||||
code; examples include "Tests:", "Packages:", or "Docker:", and also
|
||||
individual languages such as "Java:" or "Ruby:"
|
||||
|
||||
- Reference issues and PRs liberally after the subject line; if the commit
|
||||
remedies a GitHub issue, [name
|
||||
it](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)
|
||||
accordingly
|
||||
|
||||
- Don't rely on command-line commit messages with `-m`; use the editor instead
|
||||
|
24
README
24
README
|
@ -1,24 +0,0 @@
|
|||
|
||||
NGINX Unit
|
||||
----------
|
||||
|
||||
The documentation and binary packages are available online:
|
||||
|
||||
http://unit.nginx.org
|
||||
|
||||
The source code is provided under the terms of Apache License 2.0:
|
||||
|
||||
http://hg.nginx.org/unit
|
||||
|
||||
Please ask questions, report issues, and send patches to the mailing list:
|
||||
|
||||
unit@nginx.org (http://mailman.nginx.org/mailman/listinfo/unit)
|
||||
|
||||
or via Github:
|
||||
|
||||
https://github.com/nginx/unit
|
||||
|
||||
--
|
||||
NGINX, Inc.
|
||||
http://nginx.com
|
||||
|
184
README.md
Normal file
184
README.md
Normal file
|
@ -0,0 +1,184 @@
|
|||
# NGINX Unit
|
||||
|
||||
## Universal Web App Server
|
||||
|
||||
![NGINX Unit Logo](docs/unitlogo.png)
|
||||
|
||||
NGINX Unit is a lightweight and versatile open-source server that has
|
||||
three core capabilities:
|
||||
|
||||
- it is an HTTP reverse proxy,
|
||||
- a web server for static media assets,
|
||||
- and an application server that runs code in seven languages.
|
||||
|
||||
We are building a universal tool that compresses several layers of the modern
|
||||
application stack into a potent, coherent solution with a focus on performance,
|
||||
low latency, and scalability. It is intended as a building block for any web
|
||||
architecture regardless of its complexity, from enterprise-scale deployments to
|
||||
your pet's homepage.
|
||||
|
||||
Unit's native RESTful JSON API enables dynamic updates with zero interruptions
|
||||
and flexible configuration, while its out-of-the-box productivity reliably
|
||||
scales to production-grade workloads. We achieve that with a complex,
|
||||
asynchronous, multithreading architecture comprising multiple processes to
|
||||
ensure security and robustness while getting the most out of today's computing
|
||||
platforms.
|
||||
|
||||
|
||||
## Quick Installation
|
||||
|
||||
### macOS
|
||||
|
||||
``` console
|
||||
$ brew install nginx/unit/unit
|
||||
```
|
||||
|
||||
For details and available language packages, see the
|
||||
[docs](https://unit.nginx.org/installation/#homebrew).
|
||||
|
||||
|
||||
### Docker
|
||||
|
||||
``` console
|
||||
$ docker pull docker.io/nginx/unit
|
||||
```
|
||||
|
||||
For a description of image tags, see the
|
||||
[docs](https://unit.nginx.org/installation/#docker-images).
|
||||
|
||||
|
||||
### Amazon Linux, Fedora, RedHat
|
||||
|
||||
``` console
|
||||
$ curl -sL 'https://unit.nginx.org/_downloads/setup-unit.sh' | sudo -E bash
|
||||
# yum install unit
|
||||
```
|
||||
|
||||
For details and available language packages, see the
|
||||
[docs](https://unit.nginx.org/installation/#official-packages).
|
||||
|
||||
|
||||
### Debian, Ubuntu
|
||||
|
||||
``` console
|
||||
$ curl -sL 'https://unit.nginx.org/_downloads/setup-unit.sh' | sudo -E bash
|
||||
|
||||
# apt install unit
|
||||
```
|
||||
|
||||
For details and available language packages, see the
|
||||
[docs](https://unit.nginx.org/installation/#official-packages).
|
||||
|
||||
|
||||
## Running a Hello World App
|
||||
|
||||
Suppose you saved a PHP script as `/www/helloworld/index.php`:
|
||||
``` php
|
||||
<?php echo "Hello, PHP on Unit!"; ?>
|
||||
```
|
||||
|
||||
To run it on Unit with the `unit-php` module installed, first set up an
|
||||
application object. Let's store our first config snippet in a file called
|
||||
`config.json`:
|
||||
|
||||
``` json
|
||||
{
|
||||
"helloworld": {
|
||||
"type": "php",
|
||||
"root": "/www/helloworld/"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Saving it as a file isn't necessary, but can come in handy with larger objects.
|
||||
|
||||
Now, `PUT` it into the `config/applications` section of Unit's control API,
|
||||
usually available by default via a Unix domain socket:
|
||||
|
||||
``` console
|
||||
# curl -X PUT --data-binary @config.json --unix-socket \
|
||||
/path/to/control.unit.sock http://localhost/config/applications
|
||||
```
|
||||
``` json
|
||||
|
||||
{
|
||||
"success": "Reconfiguration done."
|
||||
}
|
||||
```
|
||||
|
||||
Next, reference the app from a listener object in the `config/listeners`
|
||||
section of the API. This time, we pass the config snippet straight from the
|
||||
command line:
|
||||
|
||||
``` console
|
||||
# curl -X PUT -d '{"127.0.0.1:8000": {"pass": "applications/helloworld"}}' \
|
||||
--unix-socket /path/to/control.unit.sock http://localhost/config/listeners
|
||||
```
|
||||
``` json
|
||||
{
|
||||
"success": "Reconfiguration done."
|
||||
}
|
||||
```
|
||||
|
||||
Now Unit accepts requests at the specified IP and port, passing them to the
|
||||
application process. Your app works!
|
||||
|
||||
``` console
|
||||
$ curl 127.0.0.1:8080
|
||||
|
||||
Hello, PHP on Unit!
|
||||
```
|
||||
|
||||
Finally, query the entire `/config` section of the control API:
|
||||
|
||||
``` console
|
||||
# curl --unix-socket /path/to/control.unit.sock http://localhost/config/
|
||||
```
|
||||
|
||||
Unit's output should contain both snippets, neatly organized:
|
||||
|
||||
``` json
|
||||
{
|
||||
"listeners": {
|
||||
"127.0.0.1:8080": {
|
||||
"pass": "applications/helloworld"
|
||||
}
|
||||
},
|
||||
|
||||
"applications": {
|
||||
"helloworld": {
|
||||
"type": "php",
|
||||
"root": "/www/helloworld/"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For full details of configuration management, see the
|
||||
[docs](https://unit.nginx.org/configuration/#configuration-management).
|
||||
|
||||
|
||||
## Community
|
||||
|
||||
- The go-to place to start asking questions and share your thoughts is
|
||||
our [Slack channel](https://nginxcommunity.slack.com/).
|
||||
|
||||
- Our [GitHub issues page](https://github.com/nginx/unit/issues) offers
|
||||
space for a more technical discussion at your own pace.
|
||||
|
||||
- The [project map](https://github.com/orgs/nginx/projects/1) on
|
||||
GitHub sheds some light on our current work and plans for the future.
|
||||
|
||||
- Our [official website](https://unit.nginx.org/) may provide answers
|
||||
not easily found otherwise.
|
||||
|
||||
- Get involved with the project by contributing! See the
|
||||
[contributing guide](CONTRIBUTING.md) for details.
|
||||
|
||||
- To reach the team directly, subscribe to the
|
||||
[mailing list](https://mailman.nginx.org/mailman/listinfo/unit).
|
||||
|
||||
- For security issues, [email us](security-alert@nginx.org), mentioning
|
||||
NGINX Unit in the subject and following the [CVSS
|
||||
v3.1](https://www.first.org/cvss/v3.1/specification-document) spec.
|
||||
|
BIN
docs/unitlogo.png
Normal file
BIN
docs/unitlogo.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 29 KiB |
Loading…
Reference in a new issue