Environment Variables

The .env file is read by the panel container. Required variables are marked required. Default values are the ones the code applies.

Application

Variable	Default	Description
APP_PORT	3000	HTTP API and web interface port
METRICS_PORT	3001	Prometheus metrics port
API_INSTANCES	1	number of API workers. max — one per core, -1 — cores minus one. Do not set more than the number of physical cores
IS_HTTP_LOGGING_ENABLED	false	log HTTP requests. Request bodies are never written
ENABLE_DEBUG_LOGS	false	verbose application logs
REMNAWAVE_BRANCH	dev	the branch the application reports on service endpoints

Database and cache

Variable	Default	Description
DATABASE_URL required	—	connection string, for example postgresql://xpanel:pass@xpanel-db:5432/xpanel?schema=public
POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB	—	used only by the PostgreSQL container; the application itself does not read them
REDIS_SOCKET	—	path to the Valkey/Redis unix socket (an alternative to host and port)
REDIS_HOST / REDIS_PORT	— / 6379	Valkey/Redis address
REDIS_USERNAME / REDIS_PASSWORD	—	if authentication is enabled
REDIS_DB	0	database number

Secrets and domains

Variable	Default	Description
APP_SECRET required	—	64 characters. Password hashes, JWT, TOTP encryption. Cannot be changed after startup
JWT_AUTH_LIFETIME required	—	access token lifetime in hours, from 12 to 168
PANEL_DOMAIN required	—	public panel address, with https://
FRONT_END_DOMAIN	*	the origin allowed to make CORS requests
SUB_PUBLIC_DOMAIN required	—	subscription domain without https:// and without a trailing slash; it goes into profile-web-page-url

Metrics

Variable	Description
METRICS_USER required	basic auth username for http://127.0.0.1:3001/metrics
METRICS_PASS required	basic auth password

warning

Without METRICS_USER and METRICS_PASS the container will not start.

Telegram

Variable	Default	Description
IS_TELEGRAM_NOTIFICATIONS_ENABLED	false	enables Telegram notifications
TELEGRAM_BOT_TOKEN	—	bot token
TELEGRAM_BOT_API_ROOT	https://api.telegram.org	Bot API address; change it if you use a local Bot API server
TELEGRAM_BOT_PROXY	—	proxy for requests to Telegram, for example socks5://proxy:1080
TELEGRAM_NOTIFY_USERS	—	chats for user events
TELEGRAM_NOTIFY_NODES	—	chats for node events
TELEGRAM_NOTIFY_CRM	—	chats for CRM events
TELEGRAM_NOTIFY_SERVICE	—	service notifications
TELEGRAM_NOTIFY_TBLOCKER	—	torrent-blocker events

Chat format: chat_id or chat_id:thread_id for topics. Separate multiple values with commas.

Webhooks

Variable	Default	Description
WEBHOOK_ENABLED	false	enables webhook delivery
WEBHOOK_URL	—	recipient address; separate multiple addresses with commas. Only http:// and https:// are allowed
WEBHOOK_SECRET_HEADER	—	payload signature secret, exactly 64 [a-zA-Z0-9] characters

See Webhooks for details.

Threshold notifications

Variable	Default	Description
BANDWIDTH_USAGE_NOTIFICATIONS_ENABLED	false	notify when a traffic threshold is reached
BANDWIDTH_USAGE_NOTIFICATIONS_THRESHOLD	[60, 80]	thresholds in percent, ascending, from 25 to 95, no more than 5 values
NOT_CONNECTED_USERS_NOTIFICATIONS_ENABLED	false	notify about users who never connected
NOT_CONNECTED_USERS_NOTIFICATIONS_AFTER_HOURS	[6, 24, 48]	hours after user creation, from 1 to 168, no more than 3 values
EXPIRATION_NOTIFICATIONS_ENABLED	false	notify about subscription expiration
EXPIRATION_NOTIFICATIONS	[-72, -48, -24, 24]	hours relative to expireAt: negative — before expiration, positive — after. From −168 to 168, zero is not allowed

Privacy and retention

Automatic cleanup is disabled by default. A single weekly job serves all tables: it runs if at least one of the SERVICE_CLEAN_USAGE_HISTORY or SERVICE_CLEAN_OLD_LOGS switches is enabled.

Variable	Default	Description
SERVICE_CLEAN_USAGE_HISTORY	false	enables traffic history cleanup
USAGE_HISTORY_RETENTION_DAYS	14	how many days to keep nodes_user_usage_history
SERVICE_CLEAN_OLD_LOGS	false	enables cleanup of personal data and node statistics
NODES_USAGE_HISTORY_RETENTION_DAYS	90	hourly node statistics
HWID_DEVICES_RETENTION_DAYS	90	user devices (hwid_user_devices); counted from the last time the device was seen
SUBSCRIPTION_REQUEST_HISTORY_RETENTION_DAYS	30	subscription request history
AUDIT_LOG_RETENTION_DAYS	30	administrator action log
SERVICE_DISABLE_USER_USAGE_RECORDS	false	do not record traffic history at all
SERVICE_DISABLE_SRH_RECORDS	false	do not record subscription request history at all
USER_USAGE_IGNORE_BELOW_BYTES	0	do not record traffic spikes below the specified number of bytes

Data minimization

If you do not need traffic history and subscription requests, it is more reliable not to collect them at all than to clean them up after the fact: SERVICE_DISABLE_USER_USAGE_RECORDS=true and SERVICE_DISABLE_SRH_RECORDS=true.

Short subscription IDs

Variable	Default	Description
SHORT_UUID_METHOD	nanoid	nanoid — random string, uuid — UUID v4, custom — your own template
SHORT_UUID_LENGTH	16	length for the nanoid method, from 16 to 64
SHORT_UUID_CUSTOM_PATTERN	—	template for the custom method. Tokens: {nanoid:N}, {alpha:N}, {digits:N}, {hex:N}, {uuid}

Example: SHORT_UUID_CUSTOM_PATTERN={hex:16}-{hex:16}-{digits:10}. The template must produce from 16 to 64 characters and at least ~64 bits of randomness.

Export to Redis Streams

Variable	Default	Description
EXPORT_TO_STREAM_ENABLED	false	publish panel events to Redis Streams
EXPORT_TO_STREAM_MAXLEN	3000	approximate message limit per stream (MAXLEN ~)

Streams: ioraw:export:user_usage (traffic deltas), ioraw:export:subscription_requests (subscription requests), ioraw:export:node_connections (connection snapshots, 1-hour retention). Handy for exporting to ClickHouse or Vector.