---

Overview

ngxctl is an open-source command-line utility that simplifies the process of creating, managing, validating, and deploying Nginx configurations.

Whether you're deploying a personal project, hosting a production API, or setting up multiple virtual hosts on a VPS, ngxctl eliminates repetitive configuration work while keeping every generated file clean, readable, and fully editable.

Instead of manually creating server blocks, enabling sites, validating syntax, and reloading Nginx, ngxctl automates the workflow through a simple and intuitive command-line interface.

The goal isn't to replace Nginx.

The goal is to make working with Nginx faster, safer, and significantly less repetitive.

---

Why ngxctl?

Working with Nginx often involves repeating the same workflow:

• Create a new configuration.
• Copy an old server block.
• Replace the domain.
• Replace the backend port.
• Enable the site.
• Test the configuration.
• Reload Nginx.

Repeat that enough times and it becomes tedious.

ngxctl automates those repetitive steps while still generating standard Nginx configuration files that you can edit manually whenever you need to.

---

Features

Configuration Generation

• Reverse proxy configuration
• Static website hosting
• Single Page Application (SPA) support
• PHP-FPM applications
• Docker reverse proxy templates
• WebSocket support
• SSL-ready templates
• HTTP → HTTPS redirects

---

Supported Backends

Backend	Supported
Node.js	✓
Express	✓
NestJS	✓
FastAPI	✓
Flask	✓
Django	✓
Go	✓
PHP-FPM	✓
Docker Containers	✓
Static Websites	✓
React	✓
Vue	✓
Svelte	✓

---

Site Management

• Create new sites
• Enable existing sites
• Disable sites
• Delete sites
• List configured sites
• Inspect configurations
• Automatic symlink management

---

Service Management

• Validate configurations using nginx -t
• Reload Nginx
• Restart Nginx
• Safe validation before reload

---

Backup & Recovery

• Automatic snapshot creation
• Timestamped backups
• Restore previous configurations
• Backup listing
• Rollback support

---

Installation

Requirements

Before installing ngxctl, ensure you have:

• Python 3.12 or newer
• Nginx installed
• Linux-based operating system

---

Install from PyPI

pip install ngxctl-cli

---

Install with pipx

pipx install git+https://github.com/thexento/ngxctl.git

---

Install from Source

Clone the repository.

git clone https://github.com/thexento/ngxctl.git

Move into the project.

cd ngxctl

Create a virtual environment.

python3 -m venv .venv
source .venv/bin/activate

Install the project.

pip install -e .

---

Quick Start

Launch the interactive setup wizard.

ngxctl create

The wizard guides you through:

• Domain name
• Site type
• Backend configuration
• Output location
• Automatic validation
• Automatic reload

---

Usage

Reverse Proxy

ngxctl create reverse-proxy \
    --domain api.example.com \
    --port 3000

Custom backend URL.

ngxctl create reverse-proxy \
    --domain api.example.com \
    --proxy-pass http://127.0.0.1:8080

Enable WebSocket support.

ngxctl create reverse-proxy \
    --domain socket.example.com \
    --port 3000 \
    --websocket

---

Static Website

ngxctl create static \
    --domain example.com \
    --root /var/www/example

SPA Support.

ngxctl create static \
    --domain app.example.com \
    --root /var/www/app/dist \
    --spa

---

PHP

ngxctl create php \
    --domain blog.example.com \
    --root /var/www/blog

---

Site Management

List all sites.

ngxctl list

Inspect a site.

ngxctl inspect mysite

Enable a site.

ngxctl enable mysite

Disable a site.

ngxctl disable mysite

Delete a site.

ngxctl delete mysite

---

Nginx Operations

Validate configuration.

ngxctl test

Reload Nginx.

ngxctl reload

Restart Nginx.

ngxctl restart

Display service status.

ngxctl status

---

Backup Management

Create a backup.

ngxctl backup create mysite

List backups.

ngxctl backup list

Restore a backup.

ngxctl backup restore mysite

Delete a backup.

ngxctl backup delete mysite

---

Environment Variables

Variable	Description	Default
NGXCTL_NGINX_DIR	Base Nginx directory	/etc/nginx
NGXCTL_SITES_AVAILABLE	Sites Available directory	/etc/nginx/sites-available
NGXCTL_SITES_ENABLED	Sites Enabled directory	/etc/nginx/sites-enabled
NGXCTL_CONF_D	conf.d directory	/etc/nginx/conf.d
NGXCTL_BACKUP_DIR	Backup directory	System Default

---

Project Structure

ngxctl/
├── commands/
├── helpers/
├── templates/
├── utils/
├── __init__.py
├── __main__.py
├── cli.py
└── generator.py

---

Design Principles

ngxctl follows a few simple principles.

• Keep commands intuitive.
• Generate clean and readable configurations.
• Avoid unnecessary complexity.
• Never apply invalid configurations.
• Keep everything modular.
• Produce standard Nginx files.
• Allow manual editing at any time.

---

Example Workflow

Generate a reverse proxy.

ngxctl create

Validate the generated configuration.

ngxctl test

Reload Nginx.

ngxctl reload

Done.

---

Contributing

Contributions are welcome.

If you would like to improve the project:

git clone https://github.com/thexento/ngxctl.git

cd ngxctl

git checkout -b feature/my-feature

# Make your changes

git commit -m "Add my feature"

git push origin feature/my-feature

Then open a Pull Request describing your changes.

Please keep contributions focused, readable, and well documented.

---

Frequently Asked Questions

Does ngxctl replace Nginx?

No.

ngxctl generates and manages Nginx configuration files. Nginx itself remains responsible for serving traffic.

---

Are generated configurations editable?

Yes.

Every generated configuration is a normal Nginx configuration file and can be modified manually.

---

Does ngxctl modify existing files?

Only when instructed to do so.

Whenever possible, backup snapshots are created before overwriting configurations.

---

Which operating systems are supported?

Currently, the primary target is Linux systems running Nginx.

---

License

This project is licensed under the MIT License.

See the LICENSE file for more information.

---