configuration

Configuration Example

This example demonstrates HyperServe's flexible configuration system and how different configuration sources interact through precedence rules.

What This Example Shows

• Three configuration methods: programmatic, JSON file, and environment variables
• Configuration precedence hierarchy
• How to override specific settings
• Best practices for production configuration

Configuration Methods

1. Programmatic Configuration (Lowest Priority)

server, err := server.NewServer(
    server.WithAddr(":8080"),
    server.WithRateLimit(100, 200),
)

Use when:

• You have static configuration needs
• Configuration is computed at runtime
• Setting defaults in your application

2. JSON Configuration File (Medium Priority)

{
  "addr": ":8080",
  "rate_limit": 100,
  "burst": 200
}

Use when:

• You want file-based configuration
• Different configs for different environments
• Configuration managed by ops teams

3. Environment Variables (Highest Priority)

export HS_PORT=8080
export HS_RATE_LIMIT=100
export HS_BURST_LIMIT=200

Use when:

• Running in containers (Docker, Kubernetes)
• Need to override settings without rebuilding
• Following 12-factor app principles

Running the Example

go run main.go

The example runs through all configuration methods interactively, showing:

1. Programmatic configuration only
2. JSON file configuration
3. Environment variable configuration
4. Combined configuration demonstrating precedence

Configuration Precedence

The precedence order is:

1. Environment Variables (highest)
2. JSON Configuration File
3. Programmatic Options (lowest)

This means:

• Environment variables always win
• JSON config overrides programmatic options
• Programmatic options provide defaults

Available Configuration Options

JSON Configuration Example

Create a file config.json:

{
  "addr": ":8080",
  "rate_limit": 100,
  "burst": 200,
  "static_dir": "./static",
  "template_dir": "./templates"
}

Then either:

# Set via environment variable
export HS_CONFIG_PATH=config.json
go run myapp.go

Environment Variables Example

# Basic configuration
export HS_PORT=8080

# Rate limiting
export HS_RATE_LIMIT=50
export HS_BURST_LIMIT=100

# Timeouts (use Go duration format)
export HS_READ_TIMEOUT=30s
export HS_WRITE_TIMEOUT=30s

# TLS
export HS_TLS_CERT_FILE=/path/to/cert.pem
export HS_TLS_KEY_FILE=/path/to/key.pem

# Directories
export HS_STATIC_DIR=/var/www/static
export HS_TEMPLATE_DIR=/var/www/templates

Production Best Practices

1. Use Environment Variables for Secrets

# Never put secrets in JSON files
export HS_AUTH_TOKEN_SECRET=your-secret-key
export HS_TLS_KEY_FILE=/secure/path/key.pem

2. Layer Your Configuration

// Base configuration in code
server, err := server.NewServer(
    server.WithRateLimit(100, 200),  // Defaults
)

// Override with environment-specific JSON
// config/production.json, config/staging.json, etc.

// Final overrides with environment variables
// HS_PORT, HS_LOG_LEVEL, etc.

3. Validate Configuration

if server.Options.RateLimit < 10 {
    log.Fatal("Rate limit too low for production")
}

4. Document Your Configuration

Create a .env.example file:

# Server Configuration
HS_PORT=8080

# Rate Limiting
HS_RATE_LIMIT=100
HS_BURST_LIMIT=200

# Timeouts
HS_READ_TIMEOUT=30s
HS_WRITE_TIMEOUT=30s

Docker Example

FROM golang:1.25 AS builder
WORKDIR /app
COPY . .
RUN go build -o server .

FROM alpine:latest
COPY --from=builder /app/server /server

# Default configuration
ENV HS_PORT=8080

EXPOSE 8080
CMD ["/server"]

Then override at runtime:

docker run -e HS_PORT=9090 -e HS_RATE_LIMIT=200 myapp

Kubernetes Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: hyperserve-config
data:
  server-config.json: |
    {
      "rate_limit": 100,
      "burst": 200
    }
---
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: app
        env:
        - name: HS_CONFIG_PATH
          value: /config/server-config.json
        - name: HS_PORT
          value: "8080"
        volumeMounts:
        - name: config
          mountPath: /config
      volumes:
      - name: config
        configMap:
          name: hyperserve-config

Debugging Configuration

Check the loaded configuration:

fmt.Printf("Loaded config: %+v\n", server.Options)

Or create a debug endpoint:

server.HandleFunc("/debug/config", func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(server.Options)
})

What's Next?

You've now learned the fundamentals of HyperServe! Consider exploring:

• The enterprise example for advanced security features
• The HTMX examples for modern web apps
• The main documentation for deeper topics