diff options
| -rw-r--r-- | CONTRIBUTING.md | 90 | ||||
| -rw-r--r-- | README | 24 | ||||
| -rw-r--r-- | README.md | 184 | ||||
| -rw-r--r-- | docs/unitlogo.png | bin | 0 -> 29600 bytes |
4 files changed, 274 insertions, 24 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..a7bc357b --- /dev/null +++ b/CONTRIBUTING.md @@ -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 + diff --git a/README b/README deleted file mode 100644 index f0b84a42..00000000 --- a/README +++ /dev/null @@ -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 - diff --git a/README.md b/README.md new file mode 100644 index 00000000..05bdbb91 --- /dev/null +++ b/README.md @@ -0,0 +1,184 @@ +# NGINX Unit + +## Universal Web App Server + + + +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. + diff --git a/docs/unitlogo.png b/docs/unitlogo.png Binary files differnew file mode 100644 index 00000000..dbd87fd8 --- /dev/null +++ b/docs/unitlogo.png |
