Skip to content

Configuration Reference

Complete reference for Blacklake configuration files.

.bl/config.yml

S3 Configuration

s3:
  endpoint: "https://s3.amazonaws.com"
  bucket: "blacklake-data"
  region: "us-east-1"
  access_key: "your-access-key"
  secret_key: "your-secret-key"
  use_ssl: true
  signature_version: "s3v4"
  kms_key_id: "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012"

Database Configuration

database:
  url: "postgresql://blacklake:blacklake@localhost:5432/blacklake"
  pool_size: 10
  max_overflow: 20
  pool_timeout: 30
  pool_recycle: 3600
  ssl:
    enabled: true
    mode: "require"
    cert: "/path/to/client-cert.pem"
    key: "/path/to/client-key.pem"
    ca: "/path/to/ca-cert.pem"

Solr Configuration

solr:
  url: "http://localhost:8983/solr/blacklake"
  timeout: 30
  max_retries: 3
  batch_size: 100
  username: "solr-user"
  password: "solr-password"

Server Configuration

server:
  host: "0.0.0.0"
  port: 8000
  workers: 4
  log_level: "INFO"
  log_format: "json"
  cors:
    origins: ["https://app.company.com"]
    methods: ["GET", "POST", "PUT", "DELETE"]
    headers: ["Authorization", "Content-Type"]
    credentials: true
  rate_limit:
    requests: 100
    window: 60
    burst: 200
  security:
    headers:
      - "X-Content-Type-Options: nosniff"
      - "X-Frame-Options: DENY"
      - "X-XSS-Protection: 1; mode=block"

Metadata Configuration

metadata:
  validation: true
  shacl_shapes: true
  export_formats: ["jsonld", "ttl", "nquads"]
  context_url: "https://sempervent.github.io/blacklake/ns#"
  ontology_url: "https://sempervent.github.io/blacklake/ontologies/blacklake.owl.ttl"

Authentication Configuration

auth:
  enabled: true
  jwt:
    secret: "your-jwt-secret"
    algorithm: "HS256"
    expiry: 3600
  api_keys:
    - "your-api-key-1"
    - "your-api-key-2"

Cache Configuration

cache:
  type: "redis"
  url: "redis://localhost:6379"
  ttl: 3600
  max_connections: 10

Monitoring Configuration

monitoring:
  metrics:
    enabled: true
    endpoint: "/metrics"
    format: "prometheus"
  health:
    enabled: true
    endpoint: "/health"
    detailed: true
  logging:
    level: "INFO"
    format: "json"
    file: "/var/log/blacklake/server.log"
    rotation:
      max_size: "100MB"
      max_files: 5
      compress: true

Environment-Specific Configuration

Development

# .bl/config.dev.yml
s3:
  endpoint: "http://localhost:9000"
  bucket: "blacklake-dev"
  access_key: "minioadmin"
  secret_key: "minioadmin"

database:
  url: "postgresql://blacklake:blacklake@localhost:5432/blacklake_dev"

solr:
  url: "http://localhost:8983/solr/blacklake_dev"

server:
  host: "127.0.0.1"
  port: 8000
  log_level: "DEBUG"

Staging

# .bl/config.staging.yml
s3:
  endpoint: "https://s3-staging.amazonaws.com"
  bucket: "blacklake-staging"
  region: "us-west-2"

database:
  url: "postgresql://blacklake:blacklake@staging-db:5432/blacklake_staging"

solr:
  url: "http://staging-solr:8983/solr/blacklake_staging"

server:
  host: "0.0.0.0"
  port: 8000
  workers: 2

Production

# .bl/config.prod.yml
s3:
  endpoint: "https://s3.amazonaws.com"
  bucket: "blacklake-prod"
  region: "us-west-2"
  kms_key_id: "arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012"

database:
  url: "postgresql://blacklake:secure-password@prod-db:5432/blacklake_prod"
  ssl:
    enabled: true
    mode: "require"

solr:
  url: "http://prod-solr:8983/solr/blacklake_prod"
  username: "solr-user"
  password: "secure-password"

server:
  host: "0.0.0.0"
  port: 8000
  workers: 8
  log_level: "INFO"

Configuration Precedence

  1. CLI Arguments - Highest priority
  2. Environment Variables - Second priority
  3. Configuration File - Third priority
  4. Default Values - Lowest priority

Validation

Configuration Validation

# Validate configuration
blacklake config validate

# Test connections
blacklake config test-s3
blacklake config test-db
blacklake config test-solr

Example Validation Output

✓ Configuration is valid
✓ S3 connection: OK
✓ Database connection: OK
✓ Solr connection: OK

Next Steps