Skip to content

Config Template

Nginx UI Template provides out-of-the-box configuration templates for users. In NgxConfigEditor, we offer a UI where users can quickly insert configurations from the template into the current configuration file. In this document, we will describe the file format and syntax of it.

The configuration templates are stored in template/block, and we welcome you to share your own configuration templates by open a PR.

TIP

Please note, you need to recompile the backend after modifying or adding new configuration files.

File Format

Nginx UI Template file consists of two parts: the file header and the actual Nginx configuration.

Below is a configuration template for reverse proxy, which we will use as a basis to introduce the file format and related syntax of Nginx UI Template.

nginx
# Nginx UI Template Start
name = "Reverse Proxy"
author = "@0xJacky"
description = { en = "Reverse Proxy Config", zh_CN = "反向代理配置"}

[variables.enableWebSocket]
type = "boolean"
name = { en = "Enable WebSocket", zh_CN = "启用 WebSocket"}
value = true

[variables.clientMaxBodySize]
type = "string"
name = { en = "Client Max Body Size", zh_CN = "客户端最大请求内容大小"}
value = "1000m"

[variables.scheme]
type = "select"
name = { en = "Scheme", zh_CN = "协议"}
value = "http"
mask = { http = { en = "HTTP" }, https = { en = "HTTPS" } }

[variables.host]
type = "string"
name = { en = "Host", zh_CN = "主机"}
value = "127.0.0.1"

[variables.port]
type = "string"
name = { en = "Port", zh_CN = "端口"}
value = 9000
# Nginx UI Template End

# Nginx UI Custom Start
{{- if .enableWebSocket }}
map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}
{{- end }}
# Nginx UI Custom End

if ($host != $server_name) {
    return 404;
}

location / {
        {{ if .enableWebSocket }}
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        {{ end }}

        client_max_body_size {{ .clientMaxBodySize }};

        proxy_redirect off;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_pass {{ .scheme }}://{{ .host }}:{{ .port }}/;
 }

File Header

The file header should be placed between # Nginx UI Template Start and # Nginx UI Template End, and should follow the toml syntax.

The file header includes the following fields:

FieldDescriptionTypeRequired
nameName of the configurationstringYes
authorAuthorstringYes
descriptionDesciption, uses a toml dictionary for multi-language supporttoml dictionaryYes
variables.VariableName.typeVariable type, currently supports boolean, string and selectstringYes
variables.VariableName.nameVariable display name, is a toml dictionary to support multi-languagetoml dictionaryYes
variables.VariableName.valueDefault value of the variableboolean/string (according to type definition)No
variables.VariableName.maskThe options of selecttoml dictionaryNo

Example:

toml
# Nginx UI Template Start
name = "Reverse Proxy"
author = "@0xJacky"
description = { en = "Reverse Proxy Config", zh_CN = "反向代理配置"}

[variables.enableWebSocket]
type = "boolean"
name = { en = "Enable WebSocket", zh_CN = "启用 WebSocket"}
value = true

[variables.clientMaxBodySize]
type = "string"
name = { en = "Client Max Body Size", zh_CN = "客户端最大请求内容大小"}
value = "1000m"

[variables.scheme]
type = "select"
name = { en = "Scheme", zh_CN = "协议"}
value = "http"
mask = { http = { en = "HTTP" }, https = { en = "HTTPS" } }

[variables.host]
type = "string"
name = { en = "Host", zh_CN = "主机"}
value = "127.0.0.1"

[variables.port]
type = "string"
name = { en = "Port", zh_CN = "端口"}
value = 9000
# Nginx UI Template End

The name, author, and description will be displayed in the configuration list as a summary.

Config template list

When you click the "View" button, a dialog will appear, as shown below.

The following table shows the relationship between the variable type and the UI element:

Variable TypeUI Element
booleanswitcher
stringinput
selectselect

Nginx Configuration

The Nginx configuration should be provided after the file header. This part will be parsed using the Go text/template library. This library provides powerful template generation capabilities, including conditional judgment, looping, and complex text processing, etc. For more information, please check Go Documentation.

The variables defined in the header can be used in this part, such as .scheme, .host and .port. Please note that you need to define the variables in the header in advance before using them in this part.

Here is an example:

nginx
location / {
        {{ if .enableWebSocket }}
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        {{ end }}

        client_max_body_size {{ .clientMaxBodySize }};

        proxy_redirect off;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Forwarded $proxy_add_forwarded;

        proxy_pass {{ .scheme }}://{{ .host }}:{{ .port }}/;
 }

When users change the form, the system will automatically generate new configuration content based on the template and the input of user.

In addition to the variables defined in the template header, we also provide macro-defined variables, as shown in the table below:

Variable NameDescription
HTTPPORTNginx UI listening port
HTTP01PORTPort for HTTP01 Challenge

The variables above can be used directly in the configuration part without definition in the header.

Released under the AGPL-3.0 License. (32663e1c)