Skip to main content
Guccho uses environment variables for sensitive configuration like database credentials and API keys. This guide covers how to set up and use environment variables in your configuration files.

​
Setting Up Environment Variables

Create a .env file in your project root by copying the example: 
cp .env.example .env
Then edit .env with your actual values: 
# Base URL for your site
NUXT_PUBLIC_BASE_URL=ppy.sb

# Database connection (required for bancho.py and [email protected])
DB_DSN=mysql://username:password@localhost:3306/database

# Redis connection (required if using redis session store)
REDIS_URL=redis://localhost

# Production deployment (optional)
# HOST=127.0.0.1
Never commit your .env file to version control! It should be listed in .gitignore.

​
Environment Variable Functions

Guccho provides two utility functions for accessing environment variables in your configuration files:

​
env() - Required Variables

​
env(key)
function
Retrieves a required environment variable. If the variable is not set, Guccho will fail to start.Use this for:
  • Essential credentials like database connections
  • Required API keys
  • Any configuration that must be present
import { env } from './src/server/common/utils'

export default {
  dsn: env('DB_DSN'),  // Required - app won't start without it
}
The absence of a required variable will prevent Guccho from launching with a clear error message.

​
safeEnv() - Optional Variables

​
safeEnv(key)
function
Retrieves an optional environment variable. Returns undefined if not set.Use this for:
  • Optional configuration with sensible defaults
  • Feature flags
  • Non-critical settings
import { safeEnv } from './src/server/common/utils'

export default {
  // Falls back to localhost if REDIS_URL is not set
  redisURL: safeEnv('REDIS_URL') ?? 'redis://localhost',
}
Use the nullish coalescing operator (??) to provide default values when the variable is not set.

​
Common Environment Variables

​
Database Connection

​
DB_DSN
string
required
MySQL database connection string.Format: mysql://username:password@host:port/databaseExample:
DB_DSN=mysql://guccho:secretpass@localhost:3306/gulag
Used in configuration:
dsn: env('DB_DSN')
This is required for both bancho.py and [email protected] adapters.

​
Redis Connection

​
REDIS_URL
string
Redis server connection URL.Format: redis://host:portDefault: redis://localhostExample:
REDIS_URL=redis://localhost:6379
With authentication:
REDIS_URL=redis://:password@localhost:6379
Used in configuration:
redisURL: safeEnv('REDIS_URL') ?? 'redis://localhost'
Required if you set sessionStore: 'redis' in your backend configuration.

​
Public Base URL

​
NUXT_PUBLIC_BASE_URL
string
Public-facing base URL for your server. This is accessible in both server and client code.Example:
NUXT_PUBLIC_BASE_URL=ppy.sb
Variables prefixed with NUXT_PUBLIC_ are exposed to the client-side code. See Nuxt runtime config for details.

​
Production Deployment

​
HOST
string
IP address to bind the server to in production.Default: 0.0.0.0 (all interfaces)Example:
HOST=127.0.0.1
Use 127.0.0.1 to only accept local connections, or 0.0.0.0 to accept connections from any interface.

​
Usage Examples

​
Required Database Connection

import { env } from './src/server/common/utils'

export default {
  // Will throw error if DB_DSN is not set
  dsn: env('DB_DSN'),
}

# .env
DB_DSN=mysql://user:pass@localhost:3306/gulag

​
Optional Redis with Fallback

import { safeEnv } from './src/server/common/utils'

export default {
  // Falls back to localhost if not set
  redisURL: safeEnv('REDIS_URL') ?? 'redis://localhost',
}

# .env
# Uncomment to override default
# REDIS_URL=redis://redis.example.com:6379

​
Multiple Fallback Levels

import { safeEnv } from './src/server/common/utils'

export default {
  apiUrl: safeEnv('API_URL') ?? safeEnv('FALLBACK_API_URL') ?? 'http://localhost:3000',
}

​
Backend Adapter Requirements

Required:
  • DB_DSN - MySQL database connection
Optional:
  • REDIS_URL - Redis connection (recommended for production)
# .env for bancho.py
DB_DSN=mysql://username:password@localhost:3306/database
REDIS_URL=redis://localhost

​
Environment-Specific Configuration

​
Development

# .env.development
DB_DSN=mysql://dev:dev@localhost:3306/gulag_dev
REDIS_URL=redis://localhost:6379
NUXT_PUBLIC_BASE_URL=localhost:3000

​
Production

# .env.production
DB_DSN=mysql://prod_user:[email protected]:3306/gulag_prod
REDIS_URL=redis://:[email protected]:6379
NUXT_PUBLIC_BASE_URL=ppy.sb
HOST=127.0.0.1
Use strong, unique passwords in production environments.

​
Best Practices

1

Never commit secrets

Ensure .env is in your .gitignore file:
# .gitignore
.env
.env.local
.env.*.local
2

Use env() for required values

Required configuration should use env() to fail fast:
dsn: env('DB_DSN'),  // App won't start without this
3

Provide sensible defaults

Optional configuration should have defaults using safeEnv():
redisURL: safeEnv('REDIS_URL') ?? 'redis://localhost',
4

Document your variables

Keep .env.example updated with all required variables:
# Database (required)
DB_DSN=mysql://username:password@localhost:3306/database

# Redis (optional, defaults to localhost)
# REDIS_URL=redis://localhost

​
Troubleshooting

​
”env validation error”

If you see this error, a required environment variable is missing or invalid: 
env validation error:
DB_DSN is required
Solution: Check that all required variables are set in your .env file.

​
Variables not loading

  1. Ensure .env is in the project root directory
  2. Restart the development server after changing .env
  3. Check for typos in variable names (they’re case-sensitive)

​
Connection refused errors

If database or Redis connections fail:
  1. Verify the service is running: mysql or redis-cli
  2. Check the connection string format
  3. Ensure firewall rules allow connections
  4. Test credentials manually

​
Next Steps

Backend Configuration

Use environment variables in backend config

UI Configuration

Configure UI settings and branding

Build docs developers (and LLMs) love

Get started for freeTalk to us