# Auto Nginx Installation Script
This script is designed to install Nginx on modern Ubuntu, other Debian-based systems might also work.
## Supported Modules
- Many common first-party modules (Check auto-generated `config.yaml` for details)
- [Dynamic Record Resizing for TLS](https://github.com/nginx-modules/ngx_http_tls_dyn_size)
- [brotli](https://github.com/google/ngx_brotli)
- [headers-more](https://github.com/openresty/headers-more-nginx-module)
- [geoip2](https://github.com/leev/ngx_http_geoip2_module)
- [fancyindex](https://github.com/aperezdc/ngx-fancyindex)
- OpenSSL from source
- [Zlib-Cloudflare](https://github.com/cloudflare/zlib) from source
- [Substitutions Filter](https://github.com/yaoweibin/ngx_http_substitutions_filter_module)
- [Development Kit](https://github.com/vision5/ngx_devel_kit)
Go to discussions to request more modules.
## Installation
```bash
pip install -U nginx-install
```
or
```bash
git clone https://github.com/VermiIIi0n/nginx_install.git
cd nginx_install
pip install -U poetry
poetry install
```
## Quick Start
Create a `config.yaml`, use any `action` as the first argument, it won't actually run if `config.yaml` is not found.
```bash
nginx-install uninstall --dry ## creates a config.yaml file and quits
```
Edit your `config.yaml` and run the following command to install Nginx:
```bash
nginx-install install
```
To uninstall Nginx, use the following command:
```bash
nginx-install uninstall
```
## Usage
### Installed by `pip`
```bash
nginx-install { prepare | build | install | uninstall | clean } [build_dir]
```
When you first run the script, you will be asked to create a `config.yaml` under the current directory. You may not want to run as root when creating the `config.yaml` file.
You can also specify the file using the `-c`/`--config` option.
The first positional argument is the action to be performed.
The second positional argument is optional and is used to specify the build directory. If not specified, the default build directory is used.
When running the script for real business, you might want to run as root, because the script needs to install packages and create directories.
To just build the Nginx binary, use the following command:
```bash
nginx-install build
```
To just install without building, use the following command:
```bash
nginx-install install --no-build
```
To build and install Nginx, use the following command:
```bash
nginx-install install
```
**`build` and plain `install` both delete the previous build directory and create a new one.**
Currently only partial support for cross-compiling. If your target system is the same as the build system, you can copy the build directory to the target system and run `install --no-build` there.
**Change `-march` in `config.yaml` if your are installing on systems with different CPU**
By default, `core` installer will use `-march=native` flag, this may cause problems on other systems.
Check your `-march` by running `gcc -march=native -Q --help=target | grep march` on your target system and change `-march` in `config.yaml` accordingly.
### Installed by `git clone`
If you cloned the repository, use the following command to run the script:
```bash
poetry run `which python` nginx_install <...>
```
## Dry Run
Use `--dry` to run the script in dry-run mode. In this mode, the script will not change anything outside of `build_dir` but will print the commands to be executed.
```bash
nginx-install --dry build
```
**no root should be required if you have access to the build directory.**
## Configuration
The `config.yaml` file is used to specify the version of Nginx to be installed, the modules to be included, and the build options.
Use `-c`/`--config` to specify the path of the `config.yaml` file. By default, it is `config.yaml` under the current directory.
If not specified, the script will search for the `./config.yaml` file, and if not found, it will ask you to create one.
If `-q`/`--quiet` is specified, the script will not ask you to create one and will exit with an error if not found.
Useful options in `config.yaml`:
- `version`: The version of Nginx to be installed. Can be `stable`, `mainline`, `latest`, or a simple spec version (e.g. `1.21.3`, `^1.24.0`, `<=1.26.0`).
- `core.flavor`: Can be vanilla and openresty
- `pymodule_paths`: A list of paths to Python modules. Convenient for adding custom `Installer` classes.
## Customization
You can easily add your own modules to modify the installation of Nginx (e.g. add custom modules, change build options, etc.).
All `Installer` classes are descendants of the `BaseInstaller` class.
Every `Installer` class has 5 `async` methods corresponding to the 5 stages of the installation process:
- `prepare`
- `build`
- `install`
- `uninstall`
- `clean`
They all accept a special [`context`](#context) parameter, which contains useful information about the installation process. You must override these methods in inherited classes.
During installation running, installers go through `prepare`, `build`, `install` and `clean` stages. During uninstallation running, installers go through `uninstall` and `clean` stages.
A special `Installer` called `core` represents the core binary installer of Nginx. In every stage, the core installer methods are called first, and then the methods of other installers are called. The order of the other installers is random. This is done to reduce build time.
You can access `core` through the `context` parameter. Parameters like Nginx `configure options` are stored in `core` and can be modified.
### Context
The `context` parameter is a dictionary containing the following attributes:
- `build_dir`: The build directory.
- `cfg`: The `Config` object from the `config.yaml` file.
- `core`: The `NginxInstaller` object.
- `verbose`: A boolean value indicating whether to print verbose information.
- `quiet`: A boolean value indicating whether to print nothing unless an error occurs.
- `dry_run`: A boolean value indicating whether to run the script in dry-run mode. You should respect this value in your custom installers. Don't actually change anything if `dry_run` is `True`.
- `user`: The user who started the script.
- `client`: A `httpx.AsyncClient` object. You can use it to download files from the internet.
- `logger`: You can use it to log information.
- `progress`: A `rich.progress.Progress` object. You can use it to show a progress bar.
- `run_cmd`: An `async` function to run shell commands. You should use it to run shell commands in your custom installers. When `dry_run` is `True`, it will only print the command to be executed.
- `download`: An `async` function to download files from the internet. You should use it to download files in your custom installers. It automatically shows a progress bar when downloading files.
Raw data
{
"_id": null,
"home_page": "https://github.com/VermiIIi0n/nginx_install",
"name": "nginx-install",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "utilities,nginx,automation",
"author": "VermiIIi0n",
"author_email": "dungeon.behind0t@icloud.com",
"download_url": "https://files.pythonhosted.org/packages/f6/7d/89f5e684387ed036440ac6d3ca97b367ec5a918c7dc6756893a9b167f6b5/nginx_install-0.1.7.tar.gz",
"platform": null,
"description": "# Auto Nginx Installation Script\n\nThis script is designed to install Nginx on modern Ubuntu, other Debian-based systems might also work.\n\n## Supported Modules\n\n- Many common first-party modules (Check auto-generated `config.yaml` for details)\n- [Dynamic Record Resizing for TLS](https://github.com/nginx-modules/ngx_http_tls_dyn_size)\n- [brotli](https://github.com/google/ngx_brotli)\n- [headers-more](https://github.com/openresty/headers-more-nginx-module)\n- [geoip2](https://github.com/leev/ngx_http_geoip2_module)\n- [fancyindex](https://github.com/aperezdc/ngx-fancyindex)\n- OpenSSL from source\n- [Zlib-Cloudflare](https://github.com/cloudflare/zlib) from source\n- [Substitutions Filter](https://github.com/yaoweibin/ngx_http_substitutions_filter_module)\n- [Development Kit](https://github.com/vision5/ngx_devel_kit)\n\nGo to discussions to request more modules.\n\n## Installation\n\n```bash\npip install -U nginx-install\n```\n\nor\n\n```bash\ngit clone https://github.com/VermiIIi0n/nginx_install.git\ncd nginx_install\npip install -U poetry\npoetry install\n```\n\n## Quick Start\n\nCreate a `config.yaml`, use any `action` as the first argument, it won't actually run if `config.yaml` is not found.\n\n```bash\nnginx-install uninstall --dry ## creates a config.yaml file and quits\n```\n\nEdit your `config.yaml` and run the following command to install Nginx:\n\n```bash\nnginx-install install\n```\n\nTo uninstall Nginx, use the following command:\n\n```bash\nnginx-install uninstall\n```\n\n## Usage\n\n### Installed by `pip`\n\n```bash\nnginx-install { prepare | build | install | uninstall | clean } [build_dir]\n```\n\nWhen you first run the script, you will be asked to create a `config.yaml` under the current directory. You may not want to run as root when creating the `config.yaml` file.\nYou can also specify the file using the `-c`/`--config` option.\n\nThe first positional argument is the action to be performed.\n\nThe second positional argument is optional and is used to specify the build directory. If not specified, the default build directory is used.\n\nWhen running the script for real business, you might want to run as root, because the script needs to install packages and create directories.\n\nTo just build the Nginx binary, use the following command:\n\n```bash\nnginx-install build\n```\n\nTo just install without building, use the following command:\n\n```bash\nnginx-install install --no-build\n```\n\nTo build and install Nginx, use the following command:\n\n```bash\nnginx-install install\n```\n\n**`build` and plain `install` both delete the previous build directory and create a new one.**\n\nCurrently only partial support for cross-compiling. If your target system is the same as the build system, you can copy the build directory to the target system and run `install --no-build` there.\n\n**Change `-march` in `config.yaml` if your are installing on systems with different CPU**\n\nBy default, `core` installer will use `-march=native` flag, this may cause problems on other systems.\n\nCheck your `-march` by running `gcc -march=native -Q --help=target | grep march` on your target system and change `-march` in `config.yaml` accordingly.\n\n### Installed by `git clone`\n\nIf you cloned the repository, use the following command to run the script:\n\n```bash\npoetry run `which python` nginx_install <...>\n```\n\n## Dry Run\n\nUse `--dry` to run the script in dry-run mode. In this mode, the script will not change anything outside of `build_dir` but will print the commands to be executed.\n\n```bash\nnginx-install --dry build\n```\n\n**no root should be required if you have access to the build directory.**\n\n## Configuration\n\nThe `config.yaml` file is used to specify the version of Nginx to be installed, the modules to be included, and the build options.\n\nUse `-c`/`--config` to specify the path of the `config.yaml` file. By default, it is `config.yaml` under the current directory.\n\nIf not specified, the script will search for the `./config.yaml` file, and if not found, it will ask you to create one.\n\nIf `-q`/`--quiet` is specified, the script will not ask you to create one and will exit with an error if not found.\n\nUseful options in `config.yaml`:\n\n- `version`: The version of Nginx to be installed. Can be `stable`, `mainline`, `latest`, or a simple spec version (e.g. `1.21.3`, `^1.24.0`, `<=1.26.0`).\n- `core.flavor`: Can be vanilla and openresty\n- `pymodule_paths`: A list of paths to Python modules. Convenient for adding custom `Installer` classes.\n\n## Customization\n\nYou can easily add your own modules to modify the installation of Nginx (e.g. add custom modules, change build options, etc.).\n\nAll `Installer` classes are descendants of the `BaseInstaller` class.\n\nEvery `Installer` class has 5 `async` methods corresponding to the 5 stages of the installation process:\n\n- `prepare`\n- `build`\n- `install`\n- `uninstall`\n- `clean`\n\nThey all accept a special [`context`](#context) parameter, which contains useful information about the installation process. You must override these methods in inherited classes.\n\nDuring installation running, installers go through `prepare`, `build`, `install` and `clean` stages. During uninstallation running, installers go through `uninstall` and `clean` stages.\n\nA special `Installer` called `core` represents the core binary installer of Nginx. In every stage, the core installer methods are called first, and then the methods of other installers are called. The order of the other installers is random. This is done to reduce build time.\n\nYou can access `core` through the `context` parameter. Parameters like Nginx `configure options` are stored in `core` and can be modified.\n\n### Context\n\nThe `context` parameter is a dictionary containing the following attributes:\n\n- `build_dir`: The build directory.\n- `cfg`: The `Config` object from the `config.yaml` file.\n- `core`: The `NginxInstaller` object.\n- `verbose`: A boolean value indicating whether to print verbose information.\n- `quiet`: A boolean value indicating whether to print nothing unless an error occurs.\n- `dry_run`: A boolean value indicating whether to run the script in dry-run mode. You should respect this value in your custom installers. Don't actually change anything if `dry_run` is `True`.\n- `user`: The user who started the script.\n- `client`: A `httpx.AsyncClient` object. You can use it to download files from the internet.\n- `logger`: You can use it to log information.\n- `progress`: A `rich.progress.Progress` object. You can use it to show a progress bar.\n- `run_cmd`: An `async` function to run shell commands. You should use it to run shell commands in your custom installers. When `dry_run` is `True`, it will only print the command to be executed.\n- `download`: An `async` function to download files from the internet. You should use it to download files in your custom installers. It automatically shows a progress bar when downloading files.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Auto Nginx Installation",
"version": "0.1.7",
"project_urls": {
"Homepage": "https://github.com/VermiIIi0n/nginx_install",
"Issues": "https://github.com/VermiIIi0n/nginx_install/issues"
},
"split_keywords": [
"utilities",
"nginx",
"automation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a2edee97d71ea92045cb4c57c6b850e75ae56dbe877a8ef539e32357b3767c11",
"md5": "8e5301c059df28d8e6149cc70acfe2b0",
"sha256": "ed258dbdb9720b41a77d86f26f95ac32b6b2a28ed2551ea39a77d6bc25f72d3f"
},
"downloads": -1,
"filename": "nginx_install-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8e5301c059df28d8e6149cc70acfe2b0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 25723,
"upload_time": "2024-03-08T15:26:30",
"upload_time_iso_8601": "2024-03-08T15:26:30.836004Z",
"url": "https://files.pythonhosted.org/packages/a2/ed/ee97d71ea92045cb4c57c6b850e75ae56dbe877a8ef539e32357b3767c11/nginx_install-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f67d89f5e684387ed036440ac6d3ca97b367ec5a918c7dc6756893a9b167f6b5",
"md5": "02f84b76ce51709d1e75b290f651ed21",
"sha256": "1731c3ee4c15f0ee051caa46f488baa4598d95bebd75e6da30474d64489e6f87"
},
"downloads": -1,
"filename": "nginx_install-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "02f84b76ce51709d1e75b290f651ed21",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 20422,
"upload_time": "2024-03-08T15:26:31",
"upload_time_iso_8601": "2024-03-08T15:26:31.999068Z",
"url": "https://files.pythonhosted.org/packages/f6/7d/89f5e684387ed036440ac6d3ca97b367ec5a918c7dc6756893a9b167f6b5/nginx_install-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-08 15:26:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "VermiIIi0n",
"github_project": "nginx_install",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "nginx-install"
}
JSON
