Configuration

BadgerPanel is configured through environment variables stored in the .env file at the root of your installation directory. The setup script generates this file automatically, but you can modify it at any time.

Restart Required

After changing any environment variable, you must restart the affected services for changes to take effect:

cd /opt/badgerpanel
docker compose restart api web

Environment Variables

Application

Variable	Description	Default	Required
APP_NAME	Panel display name	BadgerPanel	No
APP_URL	Public URL of the panel	--	Yes
APP_ENV	Environment mode (production, development)	production	Yes
APP_DEBUG	Enable debug logging	false	No
APP_TIMEZONE	Default timezone (IANA format)	UTC	No
APP_PORT	Internal API server port	8080	No

# Example
APP_NAME=BadgerPanel
APP_URL=https://panel.your-domain.com
APP_ENV=production
APP_DEBUG=false
APP_TIMEZONE=America/New_York
APP_PORT=8080

Database (MySQL)

Variable	Description	Default	Required
DB_HOST	MySQL server hostname	mysql	Yes
DB_PORT	MySQL server port	3306	Yes
DB_DATABASE	Database name	badgerpanel	Yes
DB_USERNAME	Database username	badgerpanel	Yes
DB_PASSWORD	Database password	--	Yes
DB_ROOT_PASSWORD	MySQL root password (Docker Compose)	--	Yes

# Example (generated by setup script)
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=badgerpanel
DB_USERNAME=badgerpanel
DB_PASSWORD=your-generated-secure-password
DB_ROOT_PASSWORD=your-generated-root-password

Database Credentials

The DB_PASSWORD and DB_ROOT_PASSWORD values are generated automatically by the setup script. If you change them, you must also update the MySQL container's credentials. Never use weak or default passwords in production.

Redis

Variable	Description	Default	Required
REDIS_HOST	Redis server hostname	redis	Yes
REDIS_PORT	Redis server port	6379	Yes
REDIS_PASSWORD	Redis authentication password	--	Yes
REDIS_DB	Redis database number	0	No

# Example
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=your-generated-redis-password
REDIS_DB=0

MinIO (Object Storage)

Variable	Description	Default	Required
MINIO_ENDPOINT	MinIO server endpoint	minio:9000	Yes
MINIO_ACCESS_KEY	MinIO access key	--	Yes
MINIO_SECRET_KEY	MinIO secret key	--	Yes
MINIO_BUCKET	Bucket name for backups	badgerpanel	Yes
MINIO_USE_SSL	Use SSL for MinIO connection	false	No
MINIO_REGION	MinIO region	us-east-1	No

# Example
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=your-generated-access-key
MINIO_SECRET_KEY=your-generated-secret-key
MINIO_BUCKET=badgerpanel
MINIO_USE_SSL=false

JWT Authentication

Variable	Description	Default	Required
JWT_SECRET	Secret key for signing JWT tokens	--	Yes
JWT_ACCESS_EXPIRY	Access token expiry duration	15m	No
JWT_REFRESH_EXPIRY	Refresh token expiry duration	7d	No

# Example
JWT_SECRET=your-generated-jwt-secret-at-least-32-characters
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d

JWT Secret

The JWT_SECRET must be a strong, random string of at least 32 characters. Changing this value will invalidate all existing user sessions.

Email (SMTP)

Variable	Description	Default	Required
SMTP_HOST	SMTP server hostname	--	No
SMTP_PORT	SMTP server port	587	No
SMTP_USERNAME	SMTP authentication username	--	No
SMTP_PASSWORD	SMTP authentication password	--	No
SMTP_ENCRYPTION	Encryption method (tls, starttls, none)	starttls	No
SMTP_FROM_ADDRESS	Sender email address	--	No
SMTP_FROM_NAME	Sender display name	BadgerPanel	No

# Example with Mailgun
SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587
SMTP_USERNAME=postmaster@mg.your-domain.com
SMTP_PASSWORD=your-mailgun-smtp-password
SMTP_ENCRYPTION=starttls
SMTP_FROM_ADDRESS=noreply@your-domain.com
SMTP_FROM_NAME=BadgerPanel

Email Is Optional but Recommended

Email is required for account verification, password reset, and invoice delivery. Without SMTP configured, these features will not work. You can configure email later through the admin settings UI as well.

OAuth Providers

Configure social login by providing OAuth client credentials. Each provider is optional.

# Google OAuth
OAUTH_GOOGLE_ENABLED=true
OAUTH_GOOGLE_CLIENT_ID=your-google-client-id
OAUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret

# Discord OAuth
OAUTH_DISCORD_ENABLED=true
OAUTH_DISCORD_CLIENT_ID=your-discord-client-id
OAUTH_DISCORD_CLIENT_SECRET=your-discord-client-secret

# GitHub OAuth
OAUTH_GITHUB_ENABLED=true
OAUTH_GITHUB_CLIENT_ID=your-github-client-id
OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret

# Microsoft OAuth
OAUTH_MICROSOFT_ENABLED=false
OAUTH_MICROSOFT_CLIENT_ID=
OAUTH_MICROSOFT_CLIENT_SECRET=

The OAuth callback URL for each provider is:

https://panel.your-domain.com/api/v1/auth/oauth/{provider}/callback

Billing / Payment Gateways

# Stripe
STRIPE_ENABLED=false
STRIPE_SECRET_KEY=sk_live_your-stripe-secret-key
STRIPE_PUBLISHABLE_KEY=pk_live_your-stripe-publishable-key
STRIPE_WEBHOOK_SECRET=whsec_your-stripe-webhook-secret

# PayPal
PAYPAL_ENABLED=false
PAYPAL_CLIENT_ID=your-paypal-client-id
PAYPAL_CLIENT_SECRET=your-paypal-client-secret
PAYPAL_MODE=live  # or "sandbox" for testing

# WHMCS
WHMCS_ENABLED=false
WHMCS_URL=https://billing.your-domain.com
WHMCS_API_IDENTIFIER=your-whmcs-api-identifier
WHMCS_API_SECRET=your-whmcs-api-secret

See the Billing Setup guide for detailed configuration instructions.

Nginx / SSL

Variable	Description	Default	Required
DOMAIN	Panel domain name	--	Yes
SSL_MODE	SSL configuration mode	letsencrypt	Yes
LETSENCRYPT_EMAIL	Email for Let's Encrypt notifications	--	Conditional

# Example
DOMAIN=panel.your-domain.com
SSL_MODE=letsencrypt
LETSENCRYPT_EMAIL=admin@your-domain.com

SSL Mode Options:

Mode	Description
letsencrypt	Automatic certificate provisioning via Let's Encrypt (recommended for production)
custom	Use your own certificate files placed in nginx/ssl/
selfsigned	Generate self-signed certificates (development only)

See the SSL Certificates guide for more details.

Admin Panel Settings

In addition to environment variables, many settings can be configured through the admin web interface at Admin > Settings. These settings are stored in the database and override some defaults.

General Settings

• Panel Name -- Displayed in the header and emails
• Panel Description -- Shown on the login page
• Panel URL -- Must match your actual domain
• Default Timezone -- Applied to new user accounts
• Registration -- Enable or disable new account registration
• Email Verification -- Require email verification before account activation
• Maintenance Mode -- Temporarily disable the panel for all non-admin users

Security Settings

• Session Timeout -- Duration before inactive sessions expire
• Max Login Attempts -- Failed attempts before account lockout
• Lockout Duration -- How long accounts remain locked
• 2FA Policy -- Optional, encouraged, or required for all users
• Password Requirements -- Minimum length and complexity rules

Rate Limiting

• Base Rate Limit -- Default API requests per minute per user
• Auth Rate Limit -- Stricter limit on login, register, and password reset endpoints
• Rate Limit per Role -- Each role has a multiplier (e.g., Admin = 2.0x the base limit)

Feature Flags

Feature flags allow you to enable or disable major features without redeployment:

Flag	Description	Default
Billing System	Enable the full billing/storefront system	Disabled
OAuth Login	Enable social login providers	Disabled
User Registration	Allow new users to create accounts	Enabled
SFTP Server	Enable SFTP access on daemon nodes	Enabled
Server Transfers	Allow migrating servers between nodes	Enabled

Configuration Precedence

When the same setting is available both as an environment variable and in the admin UI:

1. Environment variables take precedence for core infrastructure settings (database, Redis, JWT)
2. Admin UI settings take precedence for operational settings (registration, rate limits, feature flags)
3. Settings configured in the admin UI persist across restarts in the database

Next Steps

• SSL Certificates -- Configure TLS for production
• Billing Setup -- Set up payment gateways and products
• Updating the Panel -- Keep your installation up to date