---
title: Configuration
description: Full config reference with all options, YAML example, validation rules, and functional options
---

## YAML Configuration

```yaml title="config.yaml"
extensions:
  dashboard:
    # Server
    base_path: "/dashboard"
    title: "Forge Dashboard"

    # Features
    enable_realtime: true
    enable_export: true
    enable_search: true
    enable_settings: true
    enable_discovery: false
    enable_bridge: true

    # Authentication
    enable_auth: false
    login_path: "/auth/login"
    logout_path: "/auth/logout"
    default_access: "public"     # "public", "protected", "partial"

    # Data collection
    refresh_interval: "30s"
    history_duration: "1h"
    max_data_points: 1000

    # Proxy / Remote contributors
    proxy_timeout: "10s"
    cache_max_size: 1000
    cache_ttl: "30s"

    # SSE
    sse_keep_alive: "15s"

    # Security
    enable_csp: true
    enable_csrf: true

    # Theming
    theme: "auto"            # "auto", "light", "dark"
    custom_css: ""

    # Discovery
    discovery_tag: "forge-dashboard-contributor"
    discovery_poll_interval: "60s"

    # Export
    export_formats:
      - "json"
      - "csv"
      - "prometheus"
```

The extension loads config from `extensions.dashboard` first, falling back to `dashboard`.

## Programmatic Configuration

All options use the functional options pattern:

```go
ext := dashboard.NewExtension(
    dashboard.WithBasePath("/admin/dashboard"),
    dashboard.WithTitle("Admin Panel"),
    dashboard.WithRealtime(true),
    dashboard.WithExport(true),
    dashboard.WithSearch(true),
    dashboard.WithSettings(true),
    dashboard.WithBridge(true),
    dashboard.WithEnableAuth(true),
    dashboard.WithDefaultAccess("protected"),
    dashboard.WithLoginPath("/auth/login"),
    dashboard.WithRefreshInterval(30 * time.Second),
    dashboard.WithHistoryDuration(2 * time.Hour),
    dashboard.WithMaxDataPoints(2000),
    dashboard.WithTheme("auto"),
    dashboard.WithCSP(true),
    dashboard.WithCSRF(true),
)
```

## Config Reference

### Server

| Field | Type | Default | Option | Description |
|---|---|---|---|---|
| `BasePath` | `string` | `"/dashboard"` | `WithBasePath()` | HTTP base path for all dashboard routes |
| `Title` | `string` | `"Forge Dashboard"` | `WithTitle()` | Page title shown in browser tab and header |

### Features

| Field | Type | Default | Option | Description |
|---|---|---|---|---|
| `EnableRealtime` | `bool` | `true` | `WithRealtime()` | SSE real-time event stream |
| `EnableExport` | `bool` | `true` | `WithExport()` | Data export endpoints (JSON, CSV, Prometheus) |
| `EnableSearch` | `bool` | `true` | `WithSearch()` | Federated cross-contributor search |
| `EnableSettings` | `bool` | `true` | `WithSettings()` | Aggregated settings page |
| `EnableDiscovery` | `bool` | `false` | `WithDiscovery()` | Auto-discover remote contributors via service discovery |
| `EnableBridge` | `bool` | `true` | `WithBridge()` | Go-JS bridge function system |

### Authentication

| Field | Type | Default | Option | Description |
|---|---|---|---|---|
| `EnableAuth` | `bool` | `false` | `WithEnableAuth()` | Enable authentication and page access control |
| `LoginPath` | `string` | `"/auth/login"` | `WithLoginPath()` | Relative path to the login page |
| `LogoutPath` | `string` | `"/auth/logout"` | `WithLogoutPath()` | Relative path to the logout page |
| `DefaultAccess` | `string` | `"public"` | `WithDefaultAccess()` | Default access level for pages: `public`, `protected`, or `partial` |

When `EnableAuth` is `true`, every page route is wrapped with authentication middleware. Pages default to the `DefaultAccess` level unless overridden per-page via the contributor manifest `NavItem.Access` field.

An `AuthChecker` must be set on the extension at runtime (`SetAuthChecker(checker)`) to perform actual authentication validation. Without a checker, auth is effectively a no-op.

### Data Collection

| Field | Type | Default | Option | Description |
|---|---|---|---|---|
| `RefreshInterval` | `time.Duration` | `30s` | `WithRefreshInterval()` | How often to collect metrics and health data |
| `HistoryDuration` | `time.Duration` | `1h` | `WithHistoryDuration()` | How long to retain historical data points |
| `MaxDataPoints` | `int` | `1000` | `WithMaxDataPoints()` | Maximum number of data points in history |

### Proxy / Remote Contributors

| Field | Type | Default | Option | Description |
|---|---|---|---|---|
| `ProxyTimeout` | `time.Duration` | `10s` | `WithProxyTimeout()` | Timeout for requests to remote contributors |
| `CacheMaxSize` | `int` | `1000` | `WithCacheMaxSize()` | Max entries in the fragment proxy LRU cache |
| `CacheTTL` | `time.Duration` | `30s` | `WithCacheTTL()` | Time-to-live for cached remote fragments |

### SSE

| Field | Type | Default | Option | Description |
|---|---|---|---|---|
| `SSEKeepAlive` | `time.Duration` | `15s` | `WithSSEKeepAlive()` | Interval for SSE keep-alive pings |

### Security

| Field | Type | Default | Option | Description |
|---|---|---|---|---|
| `EnableCSP` | `bool` | `true` | `WithCSP()` | Add Content-Security-Policy headers |
| `EnableCSRF` | `bool` | `true` | `WithCSRF()` | CSRF token protection for forms and bridge calls |

### Theming

| Field | Type | Default | Option | Description |
|---|---|---|---|---|
| `Theme` | `string` | `"auto"` | `WithTheme()` | Theme mode: `auto`, `light`, or `dark` |
| `CustomCSS` | `string` | `""` | `WithCustomCSS()` | Custom CSS injected into the dashboard |

### Discovery

| Field | Type | Default | Option | Description |
|---|---|---|---|---|
| `DiscoveryTag` | `string` | `"forge-dashboard-contributor"` | `WithDiscoveryTag()` | Service discovery tag to filter contributors |
| `DiscoveryPollInterval` | `time.Duration` | `60s` | `WithDiscoveryPollInterval()` | How often to poll for new remote contributors |

### Export

| Field | Type | Default | Option | Description |
|---|---|---|---|---|
| `ExportFormats` | `[]string` | `["json","csv","prometheus"]` | `WithExportFormats()` | Supported export formats |

### Internal

| Field | Type | Default | Option | Description |
|---|---|---|---|---|
| `RequireConfig` | `bool` | `false` | `WithRequireConfig()` | Require config from ConfigManager (fail if missing) |

## Functional Options

All options are available as `ConfigOption` functions:

```go
// Server
dashboard.WithBasePath(path string)
dashboard.WithTitle(title string)

// Features
dashboard.WithRealtime(enabled bool)
dashboard.WithExport(enabled bool)
dashboard.WithSearch(enabled bool)
dashboard.WithSettings(enabled bool)
dashboard.WithDiscovery(enabled bool)
dashboard.WithBridge(enabled bool)

// Authentication
dashboard.WithEnableAuth(enabled bool)
dashboard.WithLoginPath(path string)
dashboard.WithLogoutPath(path string)
dashboard.WithDefaultAccess(access string)

// Data collection
dashboard.WithRefreshInterval(interval time.Duration)
dashboard.WithHistoryDuration(duration time.Duration)
dashboard.WithMaxDataPoints(maxPoints int)

// Proxy
dashboard.WithProxyTimeout(timeout time.Duration)
dashboard.WithCacheMaxSize(size int)
dashboard.WithCacheTTL(ttl time.Duration)

// SSE
dashboard.WithSSEKeepAlive(interval time.Duration)

// Security
dashboard.WithCSP(enabled bool)
dashboard.WithCSRF(enabled bool)

// Theming
dashboard.WithTheme(theme string)
dashboard.WithCustomCSS(css string)

// Discovery
dashboard.WithDiscoveryTag(tag string)
dashboard.WithDiscoveryPollInterval(interval time.Duration)

// Export
dashboard.WithExportFormats(formats []string)

// Advanced
dashboard.WithConfig(config Config)       // Set complete config
dashboard.WithRequireConfig(required bool) // Require config from ConfigManager
```

## Validation Rules

The config is validated during `Register()`. The following constraints apply:

| Field | Rule |
|---|---|
| `BasePath` | Must not be empty |
| `RefreshInterval` | Minimum 1 second |
| `MaxDataPoints` | Minimum 10 |
| `Theme` | Must be `light`, `dark`, or `auto` |
| `ProxyTimeout` | Minimum 1 second |
| `CacheMaxSize` | Must not be negative |
| `DefaultAccess` | Must be `public`, `protected`, or `partial` (when `EnableAuth` is true) |

<Callout type="warn">
If validation fails, `Register()` returns an error and the dashboard will not start.
</Callout>