Configuration Options

Complete reference for all Big Picture configuration options, including environment variables, configuration files, and validation rules.

Configuration Methods

Big Picture supports configuration via:

1. Environment Variables - BP_* prefixed variables
2. Configuration Files - YAML or TOML format
3. Helm Values - Kubernetes deployment configuration

Configuration Precedence:

1. Environment variables (highest precedence)
2. Configuration file
3. Default values (lowest precedence)

Deployment Mode

Environment Variable: BP_MODE

Configuration File:

mode: self_hosted  # or "saas", "mirror", "license_server"

Options:

• saas - Multi-tenant SaaS deployment
• self_hosted - Single-tenant self-hosted deployment
• mirror - Mirror relay mode
• license_server - Local license server mode

Default: self_hosted

Database Configuration

Environment Variables:

• BP_DATABASE_URL - Complete connection string
• BP_DATABASE_HOST - Database host
• BP_DATABASE_PORT - Database port (default: 5432)
• BP_DATABASE_NAME - Database name
• BP_DATABASE_USER - Database user
• BP_DATABASE_PASSWORD - Database password
• BP_DATABASE_SSL_MODE - SSL mode (default: require)
• BP_DATABASE_POOL_SIZE - Connection pool size (default: 10)

Configuration File:

database:
  url: "postgresql://user:pass@host:5432/bigpicture?sslmode=require"
  # Or individual fields:
  host: "postgres.example.com"
  port: 5432
  name: "bigpicture"
  user: "bigpicture"
  password: "password"
  ssl_mode: "require"
  pool_size: 10
  max_connections: 100
  connection_timeout: 30

SSL Modes: disable, allow, prefer, require, verify-ca, verify-full

Storage Configuration

Environment Variable: BP_STORAGE_TYPE

Options: s3, gcs, minio, filesystem

Default: filesystem

S3 Storage

Environment Variables:

• BP_STORAGE_S3_BUCKET - S3 bucket name
• BP_STORAGE_S3_REGION - AWS region
• BP_STORAGE_S3_ENDPOINT - Custom endpoint
• BP_STORAGE_S3_ACCESS_KEY_ID - Access key ID
• BP_STORAGE_S3_SECRET_ACCESS_KEY - Secret access key
• BP_STORAGE_S3_USE_IAM_ROLE - Use IAM role (true/false)

Configuration File:

storage:
  type: s3
  s3:
    bucket: bigpicture-artifacts
    region: us-east-1
    endpoint: ""
    access_key_id: "AKIAIOSFODNN7EXAMPLE"
    secret_access_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    use_iam_role: false

Google Cloud Storage

Environment Variables:

• BP_STORAGE_GCS_BUCKET - GCS bucket name
• BP_STORAGE_GCS_CREDENTIALS_FILE - Path to service account JSON file
• BP_STORAGE_GCS_CREDENTIALS_JSON - Service account JSON (base64 encoded)

Configuration File:

storage:
  type: gcs
  gcs:
    bucket: bigpicture-artifacts
    credentials_file: "/path/to/service-account.json"

Filesystem Storage

Environment Variable: BP_STORAGE_FILESYSTEM_PATH

Configuration File:

storage:
  type: filesystem
  filesystem:
    path: "/var/lib/bigpicture/artifacts"
    create_dirs: true

Key Management (Signer) Configuration

Environment Variable: BP_SIGNER_TYPE

Options: vault, kms, file

Default: file

Vault Signer

Environment Variables:

• BP_SIGNER_VAULT_ADDR - Vault address
• BP_SIGNER_VAULT_KEY_ID - Key ID/path in Vault
• BP_SIGNER_VAULT_ROLE - Vault role
• BP_SIGNER_VAULT_AUTH_METHOD - Auth method (kubernetes, token, approle)
• BP_SIGNER_VAULT_TOKEN - Vault token (for token auth)

Configuration File:

signer:
  type: vault
  vault:
    addr: https://vault.example.com
    key_id: bigpicture-signing-key
    role: bigpicture-signer
    auth_method: kubernetes
    auth_path: kubernetes

Cloud KMS Signer

Environment Variables:

• BP_SIGNER_KMS_PROVIDER - Provider (gcp, aws)
• BP_SIGNER_KMS_KEY_ID - Key ID/ARN

Configuration File:

signer:
  type: kms
  kms:
    provider: gcp
    project_id: my-gcp-project
    location: us-east1
    key_ring: bigpicture-keys
    key_name: signing-key

File Signer

Environment Variable: BP_SIGNER_FILE_KEY_PATH

Configuration File:

signer:
  type: file
  file:
    key_path: "/etc/bigpicture/keys/signing-key.pem"

Authentication Configuration

Environment Variable: BP_AUTH_PROVIDER

Options: oidc, static

Default: oidc

OIDC Authentication

Environment Variables:

• BP_OIDC_ISSUER - OIDC issuer URL
• BP_OIDC_CLIENT_ID - Client ID
• BP_OIDC_CLIENT_SECRET - Client secret
• BP_OIDC_SCOPES - Additional scopes (comma-separated)

Configuration File:

auth:
  provider: oidc
  oidc:
    issuer: https://accounts.google.com
    client_id: your-client-id
    client_secret: your-client-secret
    scopes:
      - openid
      - email
      - profile

Static Authentication

Environment Variable: BP_AUTH_STATIC_TOKENS

Configuration File:

auth:
  provider: static
  static:
    tokens:
      - token: "dev-token-1"
        tenant_id: "tenant-1"
        roles: ["admin"]

Server Configuration

Environment Variables:

• BP_SERVER_LISTEN_ADDR - Listen address (default: 0.0.0.0:8080)
• BP_SERVER_WORKER_THREADS - Worker threads

Configuration File:

server:
  listen_addr: "0.0.0.0:8080"
  worker_threads: 4
  max_connections: 1000
  keep_alive_timeout: 30
  read_timeout: 30
  write_timeout: 30

TLS Configuration

Environment Variables:

• BP_SERVER_TLS_ENABLED - Enable TLS (true/false)
• BP_SERVER_TLS_CERT_FILE - Certificate file path
• BP_SERVER_TLS_KEY_FILE - Private key file path

Configuration File:

server:
  tls:
    enabled: true
    cert_file: "/etc/bigpicture/tls/cert.pem"
    key_file: "/etc/bigpicture/tls/key.pem"

Logging Configuration

Environment Variable: BP_LOG_LEVEL

Options: trace, debug, info, warn, error

Default: info

Configuration File:

logging:
  level: info
  format: json  # Options: json, text

Telemetry Configuration

Environment Variables:

• BP_TELEMETRY_ENABLED - Enable telemetry (default: true)
• BP_TELEMETRY_PROMETHEUS_PORT - Prometheus metrics port (default: 9090)

Configuration File:

telemetry:
  enabled: true
  exporters:
    prometheus:
      enabled: true
      port: 9090
      path: /metrics

Mirror Configuration

Environment Variables:

• BP_MIRROR_VENDOR_URL - Vendor control plane URL
• BP_MIRROR_CREDENTIAL_TOKEN - Mirror credential token
• BP_MIRROR_ALLOWED_CHANNELS - Allowed channels (comma-separated)
• BP_MIRROR_SYNC_INTERVAL - Sync interval (default: 1h)

Configuration File:

mirror:
  vendor_url: https://vendor-bigpicture.example.com
  credential_token: mirror-secret-token
  allowed_channels:
    - stable
    - beta
  sync:
    enabled: true
    interval: 1h
    retry_attempts: 3

Licensing Configuration

Environment Variable: BP_LICENSING_DEFAULT_SEAT_ASSIGNMENT_MODE

Configuration File:

licensing:
  default_seat_assignment_mode: automatic  # or "explicit"

Options:

• automatic - Seats tracked automatically through active leases (default)
• explicit - Seats must be explicitly assigned before users can request leases

License Server Configuration

Environment Variables:

• BP_LICENSE_SERVER_MODE - Server mode (cloud, local)
• BP_LICENSE_SERVER_SYNC_ENABLED - Enable sync (true/false)
• BP_LICENSE_SERVER_SYNC_URL - Cloud server URL for sync

Configuration File:

license_server:
  mode: local
  sync:
    enabled: true
    cloud_server_url: https://cloud.bigpicture.io
    interval: 1h
    conflict_resolution: cloud_wins

Validation Rules

Required Fields:

• Database connection (url or host/name/user)
• Storage configuration (type-specific fields)
• Signer configuration (type-specific fields)
• Auth provider configuration (provider-specific fields)

Type Validation:

• URLs must be valid URLs
• Ports must be between 1 and 65535
• Durations must be valid duration strings (e.g., “1h”, “30m”, “5s”)
• Booleans must be true or false
• Enums must match valid options