Environment Variable Overrides

Relevant source files

• app.example.ini
• app/src/api/settings.ts
• app/src/views/preference/store/index.ts
• docs/.vitepress/config/en.ts
• docs/.vitepress/config/zh_CN.ts
• docs/.vitepress/config/zh_TW.ts
• docs/guide/env.md
• docs/zh_CN/guide/env.md
• docs/zh_TW/guide/env.md
• settings/settings.go
• settings/settings_test.go

Nginx UI configuration settings defined in app.ini can be overridden using environment variables. This enables containerized deployments and CI/CD environments to configure the application without modifying configuration files.

For the base configuration file structure, see page 9.1.

Overview

The environment variable override system uses the NGINX_UI_ prefix followed by section and field names. Environment variables are parsed during application initialization and take precedence over file-based configuration. The implementation uses the github.com/caarlos0/env/v11 library for type-safe parsing.

Sources: settings/settings.go72-99 settings/settings.go114-123

Naming Convention

Environment variable names follow the pattern:

NGINX_UI_<SECTION>_<FIELD_NAME> 

Where:

• NGINX_UI_ is the constant prefix defined in settings/settings.go18
• <SECTION> is the INI section name in uppercase
• <FIELD_NAME> is the struct field name converted to uppercase with underscores

Naming Examples

INI Section	INI Key	Go Struct Field	Environment Variable
[app]	PageSize	AppSettings.PageSize	NGINX_UI_APP_PAGE_SIZE
[server]	Host	ServerSettings.Host	NGINX_UI_SERVER_HOST
[nginx]	ConfigDir	NginxSettings.ConfigDir	NGINX_UI_NGINX_CONFIG_DIR
[cert]	HTTPChallengePort	CertSettings.HTTPChallengePort	NGINX_UI_CERT_HTTP_CHALLENGE_PORT

Sources: settings/settings.go18 settings/settings.go23-43

Processing Flow

Title: Environment Variable Processing During Application Initialization

Sources: settings/settings.go72-99

Implementation

envPrefixMap Structure

The envPrefixMap at settings/settings.go23-43 maps environment variable prefixes to Go struct pointers. Each entry associates a section prefix with the corresponding settings struct that will receive parsed values.

Title: envPrefixMap Section-to-Struct Mapping

Sources: settings/settings.go23-43

parseEnv Function

The parseEnv function at settings/settings.go114-123 performs type-safe environment variable parsing:

Parsing Behavior:

• Prefix Construction: Concatenates EnvPrefix (NGINX_UI_) with section prefix (e.g., SERVER_ → NGINX_UI_SERVER_)
• Field Matching: Uses struct field names directly (no tag required)
• Type Conversion: Handles int, uint, string, bool, []string automatically
• Array Parsing: Splits comma-separated values into string slices
• Error Handling: Application terminates with fatal error if parsing fails

Sources: settings/settings.go114-123 settings/settings.go18

Complete Environment Variable Reference

App Section

Configuration Field	Environment Variable	Type	Default	Description
PageSize	NGINX_UI_APP_PAGE_SIZE	int	20	Number of items per page in UI
JwtSecret	NGINX_UI_APP_JWT_SECRET	string	(empty)	JWT signing secret

Sources: app.example.ini1-3 docs/guide/env.md5-9

Server Section

Configuration Field	Environment Variable	Type	Default	Description
Host	NGINX_UI_SERVER_HOST	string	0.0.0.0	Server bind address
Port	NGINX_UI_SERVER_PORT	uint	9000	Server listen port
RunMode	NGINX_UI_SERVER_RUN_MODE	string	debug	Run mode: debug/release
EnableHTTPS	NGINX_UI_SERVER_ENABLE_HTTPS	bool	false	Enable HTTPS
EnableH2	NGINX_UI_SERVER_ENABLE_H2	bool	false	Enable HTTP/2
EnableH3	NGINX_UI_SERVER_ENABLE_H3	bool	false	Enable HTTP/3

Sources: app.example.ini5-11 docs/guide/env.md12-20

Database Section

Configuration Field	Environment Variable	Type	Default	Description
Name	NGINX_UI_DB_NAME	string	database	SQLite database filename

Sources: app.example.ini14-15 docs/guide/env.md22-25

Auth Section

Configuration Field	Environment Variable	Type	Default	Description
IPWhiteList	NGINX_UI_AUTH_IP_WHITE_LIST	[]string	(empty)	Whitelisted IP addresses (comma-separated)
BanThresholdMinutes	NGINX_UI_AUTH_BAN_THRESHOLD_MINUTES	int	10	Minutes before banned IPs expire
MaxAttempts	NGINX_UI_AUTH_MAX_ATTEMPTS	int	10	Max failed login attempts before ban

Sources: app.example.ini17-20 docs/guide/env.md27-32

Casdoor Section

Configuration Field	Environment Variable	Type	Default	Description
Endpoint	NGINX_UI_CASDOOR_ENDPOINT	string	(empty)	Casdoor server endpoint
ClientId	NGINX_UI_CASDOOR_CLIENT_ID	string	(empty)	OAuth client ID
ClientSecret	NGINX_UI_CASDOOR_CLIENT_SECRET	string	(empty)	OAuth client secret
CertificatePath	NGINX_UI_CASDOOR_CERTIFICATE_PATH	string	(empty)	Certificate file path
Organization	NGINX_UI_CASDOOR_ORGANIZATION	string	(empty)	Casdoor organization name
Application	NGINX_UI_CASDOOR_APPLICATION	string	(empty)	Casdoor application name
RedirectUri	NGINX_UI_CASDOOR_REDIRECT_URI	string	(empty)	OAuth redirect URI

Sources: app.example.ini22-29 docs/guide/env.md34-43

Cert Section

Configuration Field	Environment Variable	Type	Default	Description
Email	NGINX_UI_CERT_EMAIL	string	(empty)	ACME account email
CADir	NGINX_UI_CERT_CA_DIR	string	(empty)	Certificate authority directory
RenewalInterval	NGINX_UI_CERT_RENEWAL_INTERVAL	int	7	Days before expiry to renew
RecursiveNameservers	NGINX_UI_CERT_RECURSIVE_NAMESERVERS	[]string	(empty)	DNS servers for DNS-01 challenge
HTTPChallengePort	NGINX_UI_CERT_HTTP_CHALLENGE_PORT	string	9180	Port for HTTP-01 challenge

Sources: app.example.ini31-36 docs/guide/env.md45-52

Cluster Section

Configuration Field	Environment Variable	Type	Default	Description
Node	NGINX_UI_CLUSTER_NODE	[]string	(empty)	Cluster node URLs (comma-separated)

Example: NGINX_UI_CLUSTER_NODE="http://10.0.0.1:9000?name=node1&node_secret=secret&enabled=true,http://10.0.0.2:9000?name=node2&node_secret=secret&enabled=true"

Sources: app.example.ini38-41 docs/guide/env.md54-57

Crypto Section

Configuration Field	Environment Variable	Type	Default	Description
Secret	NGINX_UI_CRYPTO_SECRET	string	(empty)	Encryption secret for sensitive data

Sources: app.example.ini43-44 docs/guide/env.md59-62

HTTP Section

Configuration Field	Environment Variable	Type	Default	Description
GithubProxy	NGINX_UI_HTTP_GITHUB_PROXY	string	https://mirror.ghproxy.com/	GitHub proxy URL
InsecureSkipVerify	NGINX_UI_HTTP_INSECURE_SKIP_VERIFY	bool	false	Skip TLS certificate verification

Sources: app.example.ini46-48 docs/guide/env.md64-68

Logrotate Section

Configuration Field	Environment Variable	Type	Default	Description
Enabled	NGINX_UI_LOGROTATE_ENABLED	bool	false	Enable automatic log rotation
CMD	NGINX_UI_LOGROTATE_CMD	string	logrotate /etc/logrotate.d/nginx	Log rotation command
Interval	NGINX_UI_LOGROTATE_INTERVAL	int	1440	Rotation interval in minutes

Sources: app.example.ini50-53 docs/guide/env.md70-75

Nginx Section

Configuration Field	Environment Variable	Type	Default	Description
AccessLogPath	NGINX_UI_NGINX_ACCESS_LOG_PATH	string	/var/log/nginx/access.log	Default access log path
ErrorLogPath	NGINX_UI_NGINX_ERROR_LOG_PATH	string	/var/log/nginx/error.log	Default error log path
ConfigDir	NGINX_UI_NGINX_CONFIG_DIR	string	(auto-detected)	Nginx configuration directory
PIDPath	NGINX_UI_NGINX_PID_PATH	string	(auto-detected)	Nginx PID file path
SbinPath	NGINX_UI_NGINX_SBIN_PATH	string	(auto-detected)	Nginx binary path
TestConfigCmd	NGINX_UI_NGINX_TEST_CONFIG_CMD	string	(auto-detected)	Command to test config
ReloadCmd	NGINX_UI_NGINX_RELOAD_CMD	string	nginx -s reload	Command to reload Nginx
RestartCmd	NGINX_UI_NGINX_RESTART_CMD	string	(varies)	Command to restart Nginx
LogDirWhiteList	NGINX_UI_NGINX_LOG_DIR_WHITE_LIST	[]string	/var/log/nginx	Allowed log directories
StubStatusPort	NGINX_UI_NGINX_STUB_STATUS_PORT	int	0	Port for stub_status module
ContainerName	NGINX_UI_NGINX_CONTAINER_NAME	string	(empty)	Docker container name

Sources: app.example.ini55-63 docs/guide/env.md77-90

Nginx Log Section

Configuration Field	Environment Variable	Type	Default	Description
IndexingEnabled	NGINX_UI_NGINX_LOG_INDEXING_ENABLED	bool	false	Enable advanced log indexing
IndexPath	NGINX_UI_NGINX_LOG_INDEX_PATH	string	(empty)	Bleve index storage path

Sources: app.example.ini65-67 docs/guide/env.md92-96

Node Section

Configuration Field	Environment Variable	Type	Default	Description
Name	NGINX_UI_NODE_NAME	string	Local	Display name for this node
Secret	NGINX_UI_NODE_SECRET	string	(empty)	Node authentication secret
SkipInstallation	NGINX_UI_NODE_SKIP_INSTALLATION	bool	false	Skip initial setup wizard
Demo	NGINX_UI_NODE_DEMO	bool	false	Enable demo mode

Sources: app.example.ini69-73 docs/guide/env.md98-103

OpenAI Section

Configuration Field	Environment Variable	Type	Default	Description
Model	NGINX_UI_OPENAI_MODEL	string	gpt-4o	AI model name
BaseUrl	NGINX_UI_OPENAI_BASE_URL	string	(empty)	API base URL
Proxy	NGINX_UI_OPENAI_PROXY	string	(empty)	HTTP proxy for API requests
Token	NGINX_UI_OPENAI_TOKEN	string	(empty)	API authentication token
APIType	NGINX_UI_OPENAI_API_TYPE	string	(empty)	API type identifier
EnableCodeCompletion	NGINX_UI_OPENAI_ENABLE_CODE_COMPLETION	bool	false	Enable LLM code completion
CodeCompletionModel	NGINX_UI_OPENAI_CODE_COMPLETION_MODEL	string	gpt-4o-mini	Model for code completion

Sources: app.example.ini75-82 docs/guide/env.md105-111

Terminal Section

Configuration Field	Environment Variable	Type	Default	Description
StartCmd	NGINX_UI_TERMINAL_START_CMD	string	bash	Command to start terminal session

Sources: app.example.ini84-85 docs/guide/env.md113-116

WebAuthn Section

Configuration Field	Environment Variable	Type	Default	Description
RPDisplayName	NGINX_UI_WEBAUTHN_RP_DISPLAY_NAME	string	Nginx UI	Relying party display name
RPID	NGINX_UI_WEBAUTHN_RPID	string	localhost	Relying party ID (domain)
RPOrigins	NGINX_UI_WEBAUTHN_RP_ORIGINS	[]string	(multiple)	Allowed origins for WebAuthn

Sources: app.example.ini87-90 docs/guide/env.md118-124

Special Cases and Array Handling

Array/Slice Values

Configuration fields that accept multiple values (slices in Go) use comma-separated values in environment variables:

The env library automatically splits comma-separated strings into Go slices.

Sources: settings/settings_test.go26-49 settings/settings.go114-123

Predefined User Creation

When NodeSettings.SkipInstallation is true, two additional environment variables enable automatic user creation without the setup wizard:

Environment Variable	Purpose	Type
NGINX_UI_PREDEFINED_USER_NAME	Username for initial user	string
NGINX_UI_PREDEFINED_USER_PASSWORD	Password for initial user	string

Sources: docs/guide/env.md126-131

Docker-Specific Override

When running in the official Docker container (detected via helper.InNginxUIOfficialDocker()), the system overrides NginxSettings.RestartCmd to "nginx -s stop" at settings/settings.go88-90 This is necessary because the s6-overlay supervisor automatically restarts Nginx when it exits, making stop equivalent to restart.

Title: Docker Environment Detection and Override

Sources: settings/settings.go88-90

Validation and Defaults

After environment variable parsing completes, the system applies validation rules and default values at settings/settings.go78-98:

Condition	Action	Line
ServerSettings.Port == 0	Set to 9000	78-80
AuthSettings.BanThresholdMinutes <= 0	Set to 10	92-94
AuthSettings.MaxAttempts <= 0	Set to 10	96-98

Sources: settings/settings.go78-98

Usage Examples

Docker Compose Example

Kubernetes ConfigMap Example

Sources: settings/settings_test.go10-93

Testing Environment Variable Override

The test suite at settings/settings_test.go10-178 demonstrates comprehensive environment variable override testing for all configuration sections. The test:

1. Sets environment variables for all configuration sections
2. Calls Init() to load configuration
3. Asserts that environment variables override file-based configuration
4. Validates array parsing for comma-separated values
5. Confirms Docker-specific overrides

This test serves as both validation and documentation of the override system's behavior.

Sources: settings/settings_test.go10-178