sullen.net
A simple utility to manage Nginx configurations.
1# NX - Nginx Site Manager
2
3A lightweight, colorized Bash utility to manage Nginx virtual hosts using the `sites-available` / `sites-enabled` pattern.
4
5It replaces the need for manual `ln -s` and `rm` commands with a simple, human-readable interface.
6
7## Features
8
9* **Container Support**: Works in containerized contexts via environment variable configuration.
10* **Tree-view Listing**: Automatically groups subdomains under their parent domains using ASCII logic.
11 ```
12 $ sudo nx list
13 SITE STATUS
14 ---------------------------------------- ----------
15 default Disabled
16 ● example.com Enabled
17 └── ● knot.example.com Enabled
18 └── ● pds.example.com Enabled
19 └── statusphere.example.com Disabled
20 ● example.net Enabled
21 └── ● staging.example.net Enabled
22 └── wiki.example.net Disabled
23 └── ws.example.net Disabled
24 ```
25* **Status Indicators**: Color-coded feedback for "Enabled" (Green) and "Disabled" sites.
26* **Smart Suffixes**: Automatically handles .conf extensions so you don't have to type them.
27* **Integrated Testing**: Prompts to run `nginx -t` and reload the service after every edit or toggle.
28* **Config Preview**: Uses batcat (with syntax highlighting) if installed, otherwise falls back to cat.
29 ```bash
30 $ sudo nx print knot.example.com
31 ───────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
32 │ File: /etc/nginx/sites-available/knot.example.com.conf
33 ───────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
34 1 │ server {
35 2 │ listen 443 ssl;
36 3 │ listen [::]:443 ssl;
37 4 │ server_name knot.example.com;
38 5 │
39 6 │ ssl_certificate /etc/ssl/acme/example.com/fullchain.pem;
40 7 │ ssl_certificate_key /etc/ssl/acme/example.com/key.pem;
41 8 │
42 9 │ access_log /var/log/nginx/example.access.log main;
43 10 │
44 11 │ location / {
45 12 │ proxy_pass http://127.0.0.1:5555;
46 13 │ proxy_http_version 1.1;
47 14 │
48 15 │ proxy_set_header Upgrade $http_upgrade;
49 16 │ proxy_set_header Connection $connection_upgrade;
50 17 │
51 18 │ proxy_set_header Host $host;
52 19 │ proxy_set_header X-Real-IP $remote_addr;
53 20 │ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
54 21 │ proxy_set_header X-Forwarded-Proto $scheme;
55 22 │ }
56 23 │ }
57 ───────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
58 ```
59
60## Installation
61
62To install nx system-wide while keeping the source code in this repository for easy updates:
63
641. Move the repository to a permanent location (e.g., your home dir or a projects dir):
65 ```bash
66 cd ~
67 git clone https://tangled.org/sullen.net/nx
68 cd nx
69 ```
70
712. Make the script executable:
72 ```bash
73 chmod +x nx
74 ```
75
763. Create a symbolic link in your PATH:
77 ```bash
78 sudo ln -s $(pwd)/nx.sh /usr/local/bin/nx
79 ```
80
814. Ensure that your main Nginx config (e.g., `/etc/nginx/nginx.conf`) attempts to load in configurations
82at `/etc/nginx/sites-enabled/*` (or wherever you'd like to store your configurations).
83
84 ```nginx
85 # ...
86
87 http {
88 # ...
89 include /etc/nginx/sites-enabled/*;
90 }
91 ```
92
93## Usage
94
95Most commands require sudo to modify Nginx directories and reload the service.
96
97```bash
98NX - Nginx Site Manager
99
100A simple utility to manage Nginx configurations.
101
102USAGE:
103 nx <command> [arguments]
104
105COMMANDS:
106 list, l List all sites. Supports --enabled or --disabled filters.
107 enable <site> Enable a site by creating a symlink.
108 disable <site> Disable a site by removing the symlink.
109 edit, e <site> Open site config in $EDITOR.
110 cat, print, p <site> Preview site config using batcat or cat.
111
112EXAMPLES:
113 sudo nx list
114 sudo nx enable example.com
115 sudo nx disable pds.example.com
116 sudo nx e example.com
117 sudo nx print knot.example.com
118
119ENVIRONMENT:
120 EDITOR Currently set to nano
121 NX_SITES_AVAILABLE_PATH Currently set to /etc/nginx/sites-available
122 NX_SITES_ENABLED_PATH Currently set to /etc/nginx/sites-enabled
123 NX_RELOAD_CMD Currently set to systemctl reload nginx
124 NX_TEST_CMD Currently set to nginx -t
125```
126
127## Environment Variables
128
129The edit command respects your preferred editor. You can set this in your `~/.bashrc` or `~/.zshrc`:
130
131```bash
132export EDITOR='emacs'
133```
134
135Alternative `sites-available` and `sites-enabled` directories can be configured using the following
136environment variables.
137
138```bash
139export NX_SITES_AVAILABLE_PATH=<preferred-path>
140export NX_SITES_ENABLED_PATH=<preferred-path>
141```
142
143Alternative `test` and `reload` commands can be configured using the following environment variables. The following example demonstrates how this might look in a containerized context.
144
145```bash
146export NX_RELOAD_CMD='systemctl --user reload nginx'
147export NX_TEST_CMD='podman exec nginx nginx -t'
148```
149
150**Note**: To ensure your environment variables are picked up when running with sudo, use the -E flag:
151
152```bash
153sudo -E nx enable example.com
154```
155
156## License
157
158[MIT](/LICENSE.txt)