Documentation — ngxctl

01 — Setup

Installation

ngxctl requires a Linux operating system, Python 3.12 or newer, and an existing Nginx installation. Choose whichever install method fits your environment.

From PyPI (recommended)

bash

$ pip install ngxctl-cli

Using pipx (isolated global install)

bash

$ pipx install ngxctl-cli

From source (editable / development mode)

bash

$ git clone https://github.com/thexento/ngxctl.git
$ cd ngxctl
$ pip install -e .

02 — Getting started

Quick Start

The fastest way to generate a new configuration is the interactive wizard, run from inside your project directory.

bash

$ ngxctl create

The wizard walks through five steps:

Step	What it asks
Project / site name	Configuration file name — defaults to the current folder.
Domain name	Server domain name(s) — defaults to the public or local IP, or `_`.
Site type	Reverse proxy, static / SPA, or PHP.
Parameters	Port, root folder path, entrypoint file — e.g. `main.html`.
Automated setup	File generation, symlinking, syntax testing, and a non-disruptive reload.

Note: If run without sudo privileges, ngxctl automatically prompts and elevates permissions before writing to /etc/nginx/.

03 — Site types

Reverse Proxy

Generate a reverse proxy configuration non-interactively using flags.

bash

$ ngxctl create reverse-proxy \
    --site-name my-api \
    --domain api.example.com \
    --port 3000

Flag	Description
`-n, --site-name`	Custom project / site configuration name.
`-d, --domain`	Domain name(s). Defaults to the server IP.
`-p, --port`	Backend port or proxy URL. Default: `3000`.
`--websocket / --no-websocket`	Enable WebSocket proxy headers. Default: enabled.
`--enable / --no-enable`	Auto-enable the symlink. Default: enabled.
`--reload / --no-reload`	Auto-reload Nginx if the syntax test passes. Default: enabled.

With WebSocket support

bash

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

03 — Site types

Static Websites

Serve a static build directly, with optional SPA fallback routing.

bash

$ ngxctl create static \
    --site-name my-site \
    --domain example.com \
    --root /var/www/my-site

Flag	Description
`-n, --site-name`	Custom project / site configuration name.
`-d, --domain`	Domain name(s). Defaults to the server IP.
`-r, --root`	Root directory. Defaults to the current working directory.
`-e, --entrypoint`	Main HTML file. Default: `index.html`.
`--spa / --no-spa`	Enable SPA client-side routing fallback. Default: disabled.
`--enable / --no-enable`	Auto-enable the symlink. Default: enabled.
`--reload / --no-reload`	Auto-reload Nginx if the syntax test passes. Default: enabled.

Single-page application

bash

$ ngxctl create static \
    --site-name my-app \
    --domain app.example.com \
    --root /var/www/app/dist \
    --entrypoint main.html \
    --spa

03 — Site types

PHP

Generate a PHP-FPM backed server block for a given document root.

bash

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

04 — Managing sites

Site Management

Inspect and control sites once they exist. These commands read and write standard sites-available / sites-enabled symlinks.

Command	Description
`ngxctl list`	Lists all detected site configurations, active states, types, ports, and domains.
`ngxctl inspect [SITE_NAME]`	Inspects paths, symlinks, SSL state, and directives for a site. Add `-c, --show-code` to print the file contents.
`ngxctl enable [SITE_NAME]`	Symlinks the site into `sites-enabled`, tests syntax, and reloads.
`ngxctl disable [SITE_NAME]`	Removes the symlink from `sites-enabled`, tests syntax, and reloads.

bash

$ ngxctl list
$ ngxctl inspect my-app --show-code
$ ngxctl enable my-app
$ ngxctl disable my-app

05 — Service control

Nginx Operations

Direct control over the Nginx service, always preceded by a syntax check.

Command	Description
`ngxctl test`	Executes `nginx -t` validation and outputs the result.
`ngxctl reload`	Validates syntax and reloads Nginx without dropping connections.
`ngxctl restart`	Validates syntax and restarts the Nginx service.

bash

$ ngxctl test
$ ngxctl reload
$ ngxctl restart

06 — Safety net

Backups

ngxctl snapshots configurations before destructive changes, and lets you create or restore them on demand. Snapshots are stored in ~/.config/ngxctl/backups/.

Command	Description
`ngxctl backup create [SITE_NAME]`	Creates an on-demand timestamped configuration backup.
`ngxctl backup list [SITE_NAME]`	Lists stored backup snapshot files and their sizes.
`ngxctl backup restore [SITE_NAME]`	Interactively select and restore a snapshot atomically.

bash

$ ngxctl backup create my-site
$ ngxctl backup list my-site
$ ngxctl backup restore my-site

07 — Configuration

Environment Variables

ngxctl auto-detects system paths for Debian/Ubuntu, RHEL, and Homebrew installs. Override any of them explicitly:

NGXCTL_NGINX_DIR Base Nginx configuration directory. Default: /etc/nginx

NGXCTL_SITES_AVAILABLE Sites-available directory. Default: /etc/nginx/sites-available

NGXCTL_SITES_ENABLED Sites-enabled directory. Default: /etc/nginx/sites-enabled

NGXCTL_CONF_D conf.d configuration directory. Default: /etc/nginx/conf.d

NGXCTL_BACKUP_DIR Snapshot backup storage path. Default: ~/.config/ngxctl/backups

Custom templates: ngxctl renders configs with Jinja2. Place custom .j2 templates in ~/.config/ngxctl/templates/ — user templates are checked before the built-in ones in ngxctl/templates/.