API Server Config

The Bencher API Server requires a JSON configuration at startup. The configuration can be provided three ways:

• BENCHER_CONFIG environment variable: The value should be set to the JSON configuration
• BENCHER_CONFIG_PATH environment variable: The value should be set to the path of a file containing the JSON configuration
• /etc/bencher/bencher.json file: A file at this location containing the JSON configuration

If no configuration is found, then a default configuration is loaded.

To update the configuration while the server is running, an admin can use the CLI bencher server config update command which hits the PUT /v0/server/config endpoint. All updated configurations are saved to the BENCHER_CONFIG environment variable and on disk at BENCHER_CONFIG_PATH.

Example JSON configuration:

{
  "console": {
    "url": "https://bencher.example.com"
  },
  "security": {
    "issuer": "https://api.bencher.example.com",
    "secret_key": "UJu7Cpxb-zFaJYqXD-3mDDSDyj-ZvfxZFZs-X58xjxPy"
  },
  "server": {
    "bind_address": "0.0.0.0:61016",
    "request_body_max_bytes": 1048576,
    "tls": {
      "type": "as_file",
      "cert_file": "/path/to/cert.pem",
      "key_file": "/path/to/key.pem"
    }
  },
  "logging": {
    "name": "Bencher API",
    "log": {
      "stderr_terminal": {
        "level": "info"
      }
    },
  },
  "database": {
    "file": "/var/lib/bencher/data/bencher.db",
    "data_store": {
      "service": "aws_s3"
      "access_key_id": "ABC123DoRemMiABC123",
      "secret_access_key": "AA3Chr-JSF5sUQqKwayx-FvCfZKsMev-5BqPpcFC3m7",
      "access_point": "arn:aws:s3:some-region-1:123456789:accesspoint/my-bucket/path/to/backup/dir"
    }
  },
  "smtp": {
    "hostname": "mailbonobo.com",
    "port": 587,
    "starttls": true,
    "username": "bencher",
    "secret": "WM3F2u9cqSNdBPLfy9sJ5kk9",
    "from_name": "Bencher",
    "from_email": "info@bencher.example.com"
  },
  "plus": {
    "disaster_recovery": {
      "busy_timeout": 5000,
      "replicas": [
        {
          "scheme": "s3",
          "bucket": "my-bucket",
          "path": "path/to/replicate",
          "access_key_id": "ABC123DoRemMiABC123",
          "secret_access_key": "AA3Chr-JSF5sUQqKwayx-FvCfZKsMev-5BqPpcFC3m7"
        }
      ]
    },
    "stats": {
      "offset": 11242,
      "enabled": true
    }
  }
}

console

security

server

This section is based on the Dropshot server configuration.

logging

This section is based on the Dropshot logging configuration.

database

smtp

This section specifies an SMTP service configuration. The entire section is optional. If not specified, all messages will be sent to logging instead.

plus

This section is for features that are covered by the Bencher Plus License.

plus.github

This section specifies the configuration for a GitHub App used for OAuth2 authentication. You must have a valid Bencher Plus Enterprise license for at least one organization on the server. The entire section is optional. If not specified, then authentication with GitHub will not be enabled.

plus.disaster_recovery

This section specifies the disaster recovery configuration. Bencher supports continuously replicating all database changes. For running on demand or scheduled backups, see the database.data_store section of the configuration.

There are five replication schemes:

• file: Replicate to a local file path
  • path: Path to replicate to
• sftp: Replicate over SFTP
  • host: Target system hostname
  • port: Target system port number
  • user: Username on target system
  • password: (Optional) Password on target system
  • path: (Optional) Path on target system
  • key_path: (Optional) Path to SSH key
• s3: Replicate to any S3 compatible blob storage
  • bucket: Bucket name
  • path: (Optional) Path in bucket
  • endpoint: (AWS: Optional | Non-AWS: Required) Replication endpoint
  • region: (Optional) Bucket region
  • access_key_id: S3 access key
  • secret_access_key: S3 secret access key
• abs: Replicate to Azure Blob Storage
  • account_name: Account name
  • bucket: Bucket name
  • path: (Optional) Path in bucket
  • account_key: Azure account key
• gcs: Replicate to Google Cloud Storage
  • bucket: Bucket name
  • path: (Optional) Path in bucket
  • GOOGLE_APPLICATION_CREDENTIALS: Environment variable set to file path pointing to service account credentials

All five replica schemes have the following additional options:

• retention: (Optional) The amount of time that snapshot & WAL files will be kept. After the retention period, a new snapshot will be created and the old one will be removed. WAL files that exist before the oldest snapshot will also be removed. Defaults to 24h.
• retention_check_interval: (Optional) Specifies how often Bencher will check if retention needs to be enforced. Defaults to 1h.
• snapshot_interval: (Optional) Specifies how often new snapshots will be created. This is used to reduce the time to restore since newer snapshots will have fewer WAL frames to apply. Retention still applies to these snapshots. If you do not set a snapshot interval then a new snapshot will be created whenever retention is performed. Retention occurs every 24 hours by default.
• validation_interval: (Optional) When specified, Bencher will automatically restore and validate that the data on the replica matches the local copy. Disabled by default. Enabling this may significantly increase the cost of running Bencher as most cloud services charge for downloads.
• sync_interval: (Optional) Frequency in which frames are pushed to the replica. Defaults to 1s. Increasing frequency can increase cloud storage costs significantly.

plus.stats

This section specifies if and when server statistics are collected. The entire section is optional. If not specified, the listed default values will be used. That is, server statistics are opt-out. Set enabled to false to disable server statistics.