back
loading skill details...
Creates a standard Nginx/OpenResty reverse proxy config file for a service and reloads the web server. Features safety checks and environment awareness. Takes service name, domain, and port as main arguments.
---
name: nginx-config-creator
description: "Creates a standard Nginx/OpenResty reverse proxy config file for a service and reloads the web server. Features safety checks and environment awareness. Takes service name, domain, and port as main arguments."
metadata:
openclaw:
requires:
bins: ["bash", "docker"]
---
# Nginx Config Creator (Enterprise Grade)
This skill automates the creation of Nginx/OpenResty reverse proxy configurations. It is designed for both ease of use and safety, incorporating environment awareness and a critical safety-check mechanism.
## Features
- **Environment Awareness**: Simplifies commands by reading configuration from environment variables.
- **Safety Check**: Includes a '熔断' (fuse) mechanism. It tests the configuration before applying it and automatically rolls back if the test fails, preventing web server downtime.
## Pre-requisites (Recommended)
For maximum convenience, it is recommended to set the following environment variables on the host system:
- `NGINX_CONFIG_PATH`: The absolute path to the Nginx `conf.d` directory.
- `NGINX_CONTAINER_NAME`: The name of the running Nginx/OpenResty Docker container.
If these are not set, they **must** be provided as command-line arguments.
## Core Action: `scripts/create-and-reload.sh`
This script performs the entire operation.
### **Inputs (Command-Line Arguments)**
- `--service-name`: (Required) The short name for the service (e.g., `grafana`).
- `--domain`: (Required) The root domain name (e.g., `example.com`).
- `--port`: (Required) The local port the service is running on (e.g., `3000`).
- `--config-path`: (Optional) The path to Nginx's `conf.d` directory. **Overrides** the `NGINX_CONFIG_PATH` environment variable.
- `--container-name`: (Optional) The name of the Nginx Docker container. **Overrides** the `NGINX_CONTAINER_NAME` environment variable.
### **Output**
- **On Success**: Prints a step-by-step log of its actions and a final success message.
- **On Failure**: Prints a descriptive error message to stderr and exits. If the failure occurs during the Nginx configuration test, the full error from `nginx -t` is displayed.
### **Execution Workflow**
1. **Parse Arguments & Environment**: The script gathers all necessary paths and names from command-line arguments and environment variables.
2. **Generate Config**: It creates the `.conf` file in the target directory.
3. **Test Config (Safety Check)**: It executes `nginx -t` inside the specified container.
4. **Decide & Act**:
- If the test passes, it proceeds to reload Nginx via `nginx -s reload`.
- If the test fails, it **automatically deletes the generated file (rolls back)** and reports the error.
5. **Report Result**: Informs the user of the final outcome.
### **Example Usage**
**Scenario 1: Environment variables are pre-set**
```bash
# Set for future convenience
export NGINX_CONFIG_PATH="/path/to/your/nginx/conf.d"
export NGINX_CONTAINER_NAME="your_nginx_container"
# Now, the command is very simple:
bash skills/nginx-config-creator/scripts/create-and-reload.sh \
--service-name "grafana" \
--domain "example.com" \
--port "3000"
```
**Scenario 2: No environment variables (providing all info via arguments)**
```bash
bash skills/nginx-config-creator/scripts/create-and-reload.sh \
--service-name "grafana" \
--domain "example.com" \
--port "3000" \
--config-path "/path/to/your/nginx/conf.d" \
--container-name "your_nginx_container"
```
### **Failure Strategy**
- **Missing Arguments**: The script will exit with an error if required arguments/environment variables are missing.
- **`nginx -t` Fails**: The skill is designed to be safe. It will **not** attempt to reload a broken configuration. It will clean up after itself and show you the exact error, ensuring the live web server is never affected.
don't have the plugin yet? install it then click "run inline in claude" again.
added explicit decision points for missing args and docker errors, clarified edge cases like config file overwrites and permission failures, documented default env var behavior, and structured all components to implexa standards while preserving original rollback safety logic.
this skill automates creation of Nginx/OpenResty reverse proxy configurations for a given service. use it when you need to expose a locally-running service (e.g., on port 3000) to the internet via a domain name with automatic config validation and rollback on failure. it's built for both convenience and safety: reads config from environment variables when available, but doesn't reload Nginx if the generated config fails validation.
command-line arguments:
--service-name (required): short service identifier, e.g. grafana, prometheus. used in the config filename and server block name.--domain (required): root domain name, e.g. example.com. becomes the Nginx server_name directive.--port (required): local port where the service listens, e.g. 3000.--config-path (optional): absolute path to Nginx conf.d directory. overrides NGINX_CONFIG_PATH env var.--container-name (optional): name of running Nginx/OpenResty Docker container. overrides NGINX_CONTAINER_NAME env var.environment variables (optional, used if args not provided):
NGINX_CONFIG_PATH: absolute path to Nginx conf.d directory. default: /etc/nginx/conf.d.NGINX_CONTAINER_NAME: name of running Nginx/OpenResty Docker container. no default; must be provided via arg or env var.external connections:
docker exec commands inside the Nginx container.NGINX_CONTAINER_NAME.binaries required:
bash: for script execution.docker: for container command execution.parse all command-line arguments and environment variables. validate that --service-name, --domain, --port, --config-path (or NGINX_CONFIG_PATH), and --container-name (or NGINX_CONTAINER_NAME) are populated. exit with error if any required value is missing.
construct the config file path as ${NGINX_CONFIG_PATH}/${SERVICE_NAME}.conf.
generate the Nginx server block config file at that path. the config must include: server_name directive set to the domain, listen 80 (or standard Nginx default), and a proxy_pass directive pointing to http://localhost:${PORT}. do not write the file yet if doing a dry run; proceed to next step.
execute docker exec ${NGINX_CONTAINER_NAME} nginx -t to validate the generated config syntax inside the container. capture both stdout and stderr.
check the exit code from step 4. if exit code is 0, proceed to step 6. if non-zero, go to step 7.
execute docker exec ${NGINX_CONTAINER_NAME} nginx -s reload to reload Nginx with the new config. wait for the command to complete. log success message with the domain and port info. exit with code 0.
delete the config file created in step 2. log the full error output from the nginx -t command to stderr. exit with non-zero code.
if required arguments are missing: exit immediately with a usage error message listing which args/env vars are required.
if nginx -t validation passes: proceed to reload. if reload command fails (e.g., Nginx crashes), log the error but do not attempt further recovery. the config file remains on disk for manual inspection.
if nginx -t validation fails: delete the generated config file and report the validation error to the user. never reload Nginx with a broken config.
if Docker container is unreachable or does not exist: the docker exec command will fail. catch this error and inform the user that the Nginx container cannot be accessed. do not attempt fallback to host-level Nginx commands.
if the config file path is not writable: fail early during file creation attempt. report the permission error.
if the config file already exists at the target path: overwrite it without prompting. log that the old config was replaced.
on success:
${NGINX_CONFIG_PATH}/${SERVICE_NAME}.conf containing a valid Nginx server block.on failure:
nginx -t if validation was the failure point.user sees one of two outcomes:
success: skill prints a final message like "nginx config for grafana created and reloaded successfully. domain: example.com, port: 3000." user can immediately visit the domain in a browser and reach the service.
failure: skill prints an error message with the reason. if validation failed, the exact Nginx error is shown (e.g., "invalid number of arguments in 'proxy_pass' directive"). no config file is left behind. the existing Nginx config is untouched.
user can verify success by running curl http://example.com (after DNS propagation) or checking the Nginx access logs.