Configuration

Overview

Showdown Trivia is configured through environment variables defined in a .env file or set in your deployment environment. The application validates all required configuration at startup and will fail with specific error messages if any required values are missing or invalid.

Required Environment Variables

All of the following environment variables must be set for the application to start:

DB_URL

Type: String
Required: Yes Description: MongoDB connection string including authentication credentials and database name. Format:

mongodb://[username]:[password]@[host]:[port]/[database]?authSource=[authDB]

Examples:

DB_URL=mongodb://localhost:27017/trivia

The application will exit with error ErrInvalidDbUrl if this variable is empty or not set.

PORT

Type: Integer
Required: Yes
Default: None (must be explicitly set) Description: The port number on which the web server will listen for HTTP requests. Examples:

PORT=8080

The application will exit with error ErrInvalidPort if this value is not a valid integer.

Common values:

8080 - Standard alternative HTTP port (default in Docker)
3000 - Common development port
80 - Standard HTTP port (requires root/admin privileges)

LOG_LEVEL

Type: String (enum)
Required: Yes Description: Controls the verbosity of application logging. Determines which log messages are output based on their severity level. Valid values:

debug - Most verbose; includes all log levels
info - Informational messages and above
warn - Warnings and errors only
error - Error messages only

Examples:

LOG_LEVEL=debug

Behavior by environment:

Development (ENV=dev): Uses text format with source file locations, forces debug level
Production (ENV=prod): Uses JSON format with source locations, respects the configured level

The application will exit with error ErrInvalidLevel if the value is not one of: debug, info, warn, error.

ENV

Type: String (enum)
Required: Yes Description: Specifies the runtime environment, which affects logging format and behavior. Valid values:

dev - Development mode
prod - Production mode

Examples:

ENV=dev

Effects:

Aspect	dev	prod
Log Format	Text (human-readable)	JSON (machine-parseable)
Log Level Override	Always debug	Uses LOG_LEVEL setting
Source Info	Included	Included

The application will exit with error ErrInvliadEnv if the value is not dev or prod.

Complete Configuration Examples

Development (.env)

DB_URL=mongodb://localhost:27017/trivia
PORT=8080
LOG_LEVEL=debug
ENV=dev

Production (.env)

DB_URL=mongodb://admin:SecurePassword123@mongo-prod:27017/trivia?authSource=admin
PORT=8080
LOG_LEVEL=info
ENV=prod

Docker Compose (compose.yaml)

environment:
  - PORT=8080
  - DB_URL=mongodb://admin:admin11@mongo/trivia?authSource=admin
  - LOG_LEVEL=info
  - ENV=dev

Configuration Loading

The application loads configuration in the following order:

Environment variables read

The application reads all four required environment variables using os.Getenv().

Validation

Each variable is validated:

ENV: Must be “dev” or “prod”
DB_URL: Must not be empty
LOG_LEVEL: Must be one of the valid log levels
PORT: Must be a valid integer

Configuration object created

If all validations pass, a Config struct is created with the parsed values.

Logger initialized

The logger is created based on the LOG_LEVEL and ENV settings.

Loading Environment Files

With Makefile

The Makefile automatically loads variables from .env using the load_env.sh script:

make run
make air

Manually

Source the environment file before running:

source load_env.sh
go run ./cmd/web/main.go

With Docker

Docker Compose automatically reads environment variables from the compose.yaml file.

Validation Errors

The application performs strict validation and will exit with specific errors:

Error	Cause	Solution
`ErrInvalidDbUrl`	DB_URL is empty	Set valid MongoDB connection string
`ErrInvalidPort`	PORT is not a number	Set PORT to a valid integer
`ErrLogLevel`	LOG_LEVEL is empty	Set LOG_LEVEL to one of the valid values
`ErrInvalidLevel`	LOG_LEVEL value is invalid	Use: debug, info, warn, or error
`ErrInvliadEnv`	ENV is missing or invalid	Set ENV to “dev” or “prod”

Configuration in Code

The configuration is managed by the config package located in:

internal/config/config.go

Config struct:

type Config struct {
    Port     int
    DbUrl    string
    LogLevel string
    Env      string
}

Usage:

config, err := config.NewConfig()
if err != nil {
    // Application will exit if configuration is invalid
    log.Fatal(err)
}

// Access configuration values
port := config.Port
dbUrl := config.DbUrl

MongoDB Configuration Details

Connection String Parameters

The MongoDB connection string supports various parameters:

mongodb://user:pass@host:port/database?param1=value1&param2=value2

Common parameters:

authSource - Database for authentication (usually “admin”)
retryWrites=true - Enable retryable writes
w=majority - Write concern level
maxPoolSize - Maximum connection pool size
minPoolSize - Minimum connection pool size

Docker Compose MongoDB Settings

When using the provided compose.yaml, MongoDB is configured with:

MONGO_INITDB_DATABASE=trivia
MONGO_INITDB_ROOT_USERNAME=admin
MONGO_INITDB_ROOT_PASSWORD=admin11

Matching connection string:

mongodb://admin:admin11@mongo/trivia?authSource=admin

The hostname mongo refers to the Docker Compose service name and is resolved by Docker’s internal DNS.

Security Best Practices

Never commit .env files containing production credentials to version control. Add .env to your .gitignore file.

Recommendations

Use strong passwords for MongoDB authentication
Rotate credentials regularly in production
Use secrets management systems (e.g., HashiCorp Vault, AWS Secrets Manager)
Set ENV=prod in production to use JSON logging
Use LOG_LEVEL=info or warn in production to reduce log volume
Restrict PORT access with firewalls and security groups
Enable MongoDB authentication even in development
Use connection pooling parameters for production MongoDB connections

Environment-Specific Tips

Development

DB_URL=mongodb://localhost:27017/trivia
PORT=8080
LOG_LEVEL=debug
ENV=dev

Use debug level for detailed logging
Point to local MongoDB instance
Use text-formatted logs for easier reading

Staging

DB_URL=mongodb://user:pass@staging-db:27017/trivia?authSource=admin
PORT=8080
LOG_LEVEL=info
ENV=prod

Use info level to see important events
Use production-like settings
Test with JSON logs

Production

DB_URL=mongodb+srv://user:[email protected]/trivia?retryWrites=true&w=majority
PORT=8080
LOG_LEVEL=warn
ENV=prod

Use warn or error to minimize log volume
Use managed MongoDB service (Atlas, etc.)
Enable retryable writes and appropriate write concern
Use JSON logs for log aggregation tools

Troubleshooting

Application won’t start

Check all four required variables are set:
```
echo $DB_URL $PORT $LOG_LEVEL $ENV
```
Verify .env file exists and is being loaded
Check for validation error messages in the output

Environment variables not loading

Ensure load_env.sh has correct permissions:
```
chmod +x load_env.sh
```
Source the file manually:
```
source load_env.sh
```
Verify .env file format (no quotes around values needed)

MongoDB connection fails

Verify MongoDB is running:
```
mongosh $DB_URL
```
Check authentication credentials
Ensure the database specified in the URL exists
Verify network connectivity to the MongoDB host

Next Steps

Local Setup

Set up your local development environment

Docker Deployment

Deploy with Docker Compose

Get Started

Core Features

Deployment

Architecture

Overview

Required Environment Variables

DB_URL

PORT

LOG_LEVEL

ENV

Complete Configuration Examples

Development (.env)

Production (.env)

Docker Compose (compose.yaml)

Configuration Loading

Loading Environment Files

With Makefile

Manually

With Docker

Validation Errors

Configuration in Code

MongoDB Configuration Details

Connection String Parameters

Docker Compose MongoDB Settings

Security Best Practices

Recommendations

Environment-Specific Tips

Development

Staging

Production

Troubleshooting

Application won’t start

Environment variables not loading

MongoDB connection fails

Next Steps

Local Setup

Docker Deployment

Build docs developers (and LLMs) love

Get Started

Core Features

Deployment

Architecture

​Overview

​Required Environment Variables

​DB_URL

​PORT

​LOG_LEVEL

​ENV

​Complete Configuration Examples

​Development (.env)

​Production (.env)

​Docker Compose (compose.yaml)

​Configuration Loading

​Loading Environment Files

​With Makefile

​Manually

​With Docker

​Validation Errors

​Configuration in Code

​MongoDB Configuration Details

​Connection String Parameters

​Docker Compose MongoDB Settings

​Security Best Practices

​Recommendations

​Environment-Specific Tips

​Development

​Staging

​Production

​Troubleshooting

​Application won’t start

​Environment variables not loading

​MongoDB connection fails

​Next Steps

Local Setup

Docker Deployment

Build docs developers (and LLMs) love

Overview

Required Environment Variables

DB_URL

PORT

LOG_LEVEL

ENV

Complete Configuration Examples

Development (.env)

Production (.env)

Docker Compose (compose.yaml)

Configuration Loading

Loading Environment Files

With Makefile

Manually

With Docker

Validation Errors

Configuration in Code

MongoDB Configuration Details

Connection String Parameters

Docker Compose MongoDB Settings

Security Best Practices

Recommendations

Environment-Specific Tips

Development

Staging

Production

Troubleshooting

Application won’t start

Environment variables not loading

MongoDB connection fails

Next Steps