Skip to main content
StellarStack uses environment variables to configure both the API server and web panel. This guide covers all available configuration options.

​
Configuration Files

StellarStack uses separate environment files for different components:
  • apps/api/.env - API server configuration
  • apps/web/.env - Web panel configuration
  • .env - Docker Compose configuration (when using Docker)
Environment variables in .env.example files serve as templates. Copy them to .env and customize for your installation.

​
Required Variables

These variables are required for StellarStack to function:

​
Database Connection

​
DATABASE_URL
string
required
PostgreSQL connection string in the format:
DATABASE_URL="postgresql://user:password@host:port/database"
Example:
DATABASE_URL="postgresql://stellar:stellarpass@localhost:5432/stellar"
Use a strong password for production deployments. The example password is for development only.

​
Authentication Secret

​
BETTER_AUTH_SECRET
string
required
Secret key used to sign session tokens. Must be at least 32 characters.Generate a secure secret:
openssl rand -base64 32
Example:
BETTER_AUTH_SECRET="your-generated-secret-here"
Never commit this secret to version control. Keep it secure and unique per installation.

​
Production Required Variables

These variables are required for production deployments:

​
Frontend URL

​
FRONTEND_URL
string
required
The public URL where your web panel is hosted. Used for CORS, redirects, and OAuth callbacks.Example:
FRONTEND_URL="https://panel.example.com"
Do not include a trailing slash. Use https:// for production deployments with SSL.

​
API URL

​
API_URL
string
required
The public URL where your API server is hosted.Example:
API_URL="https://api.example.com"

​
Security Secrets

​
DOWNLOAD_TOKEN_SECRET
string
required
Secret used to sign file download tokens. Minimum 32 characters.Generate:
openssl rand -base64 32
​
ENCRYPTION_KEY
string
required
32-byte hexadecimal key for AES-256-CBC encryption. Used to encrypt sensitive data at rest.Generate:
openssl rand -hex 32
Example:
ENCRYPTION_KEY="a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
This must be exactly 64 hexadecimal characters (32 bytes). Losing this key will make encrypted data unrecoverable.
​
JWT_SECRET
string
required
Secret for signing JWT tokens. Minimum 32 characters.Generate:
openssl rand -base64 32

​
Optional Variables

​
OAuth Configuration

Enable login with Google, GitHub, or Discord by configuring OAuth providers:

​
Google OAuth

​
GOOGLE_CLIENT_ID
string
Google OAuth 2.0 client ID. Get from Google Cloud Console.
​
GOOGLE_CLIENT_SECRET
string
Google OAuth 2.0 client secret.
Setup Steps:
1

Create OAuth credentials

  1. Go to Google Cloud Console
  2. Create a new project or select existing
  3. Navigate to APIs & Services > Credentials
  4. Click Create Credentials > OAuth client ID
2

Configure authorized URLs

Add these authorized redirect URIs:
https://your-panel-domain.com/api/auth/callback/google
http://localhost:3000/api/auth/callback/google (for development)
3

Add credentials to .env

GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-client-secret"

​
GitHub OAuth

​
GITHUB_CLIENT_ID
string
GitHub OAuth App client ID. Get from GitHub Developer Settings.
​
GITHUB_CLIENT_SECRET
string
GitHub OAuth App client secret.
Setup Steps:
1

Create OAuth App

  1. Go to GitHub Developer Settings
  2. Click New OAuth App
  3. Fill in application details
2

Set callback URL

Authorization callback URL:
https://your-panel-domain.com/api/auth/callback/github
3

Add credentials

GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

​
Discord OAuth

​
DISCORD_CLIENT_ID
string
Discord Application client ID. Get from Discord Developer Portal.
​
DISCORD_CLIENT_SECRET
string
Discord Application client secret.
Setup Steps:
1

Create application

  1. Go to Discord Developer Portal
  2. Click New Application
  3. Name your application
2

Configure OAuth2

  1. Navigate to OAuth2 settings
  2. Add redirect URL:
https://your-panel-domain.com/api/auth/callback/discord
3

Add credentials

DISCORD_CLIENT_ID="your-discord-client-id"
DISCORD_CLIENT_SECRET="your-discord-client-secret"

​
Cloudflare Turnstile (CAPTCHA)

Protect your login page with Cloudflare Turnstile:
​
NEXT_PUBLIC_TURNSTILE_SITE_KEY
string
Turnstile site key (public). Configured in apps/web/.env.Get from Cloudflare Dashboard.
​
TURNSTILE_SECRET_KEY
string
Turnstile secret key. Configured in both apps/api/.env and apps/web/.env.
Setup:
1

Create Turnstile site

  1. Go to Cloudflare Dashboard
  2. Navigate to Turnstile
  3. Click Add Site
  4. Configure domain and widget type
2

Add keys to environment

apps/web/.env:
NEXT_PUBLIC_TURNSTILE_SITE_KEY="your-site-key"
TURNSTILE_SECRET_KEY="your-secret-key"
apps/api/.env:
TURNSTILE_SECRET_KEY="your-secret-key"
If Turnstile keys are not configured, the CAPTCHA will not be displayed on the login page.

​
Configuration Examples

​
Development Environment

apps/api/.env: 
DATABASE_URL="postgresql://stellar:stellarpass@localhost:5432/stellar"
apps/web/.env: 
# No additional configuration required for basic development

​
Production Environment

apps/api/.env: 
DATABASE_URL="postgresql://stellarstack:[email protected]:5432/stellarstack"
BETTER_AUTH_SECRET="your-32-character-secret-here"
FRONTEND_URL="https://panel.example.com"
API_URL="https://api.example.com"
DOWNLOAD_TOKEN_SECRET="your-download-token-secret"
ENCRYPTION_KEY="your-64-character-hex-encryption-key"
JWT_SECRET="your-jwt-secret"

# Optional: OAuth
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# Optional: CAPTCHA
TURNSTILE_SECRET_KEY="your-turnstile-secret"
apps/web/.env: 
# Optional: CAPTCHA
NEXT_PUBLIC_TURNSTILE_SITE_KEY="your-turnstile-site-key"
TURNSTILE_SECRET_KEY="your-turnstile-secret"

​
Applying Configuration Changes

After modifying environment variables:
Restart the development servers:
# Stop with Ctrl+C, then:
pnpm dev

​
Security Best Practices

  • Generate cryptographically secure random values for all secrets
  • Never reuse secrets across installations
  • Use different secrets for development and production
  • Never commit .env files to version control
  • Restrict file permissions: chmod 600 .env
  • Use secret management services in production (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Use SSL/TLS certificates for all production deployments
  • Configure FRONTEND_URL and API_URL with https://
  • Enable HSTS headers in your reverse proxy
  • Use strong database passwords
  • Restrict database access to application servers only
  • Enable SSL for database connections in production
  • Regularly backup your database

​
Next Steps

Create Your First Server

Set up your first game server

Advanced Configuration

Explore advanced configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us