Skip to Content
🎉 New release with new features and improvements! V0.0.4 Release →
DocumentationsBsh EngineEnvironment

Environment Configuration

The BSH Engine uses a JSON-based configuration system loaded from the BSH_CONFIG environment variable.

How Configuration Works

  1. Copy Configuration Template to create your own configuration
  2. Fill in the required values
  3. Set the BSH_CONFIG environment variable with the JSON content (stringified)
  4. The engine reads this configuration at startup and Configure your instance.

Configuration Template

{
  "env": "DEV",
  "datasource": {
    "url": "",
    "host": "",
    "port": 5432,
    "user": "",
    "password": "",
    "database": "",
    "driverClassName": "org.postgresql.Driver",
    "pool": {
      "maximumSize": 10,
      "minimumIdle": 5,
      "idleTimeout": 300000,
      "connectionTimeout": 30000,
      "maxLifetime": 1800000
    },
    "query": {
      "queryTimeout": 30,
      "fetchSize": 100
    },
    "properties": {
      "cachePrepStmts": "true",
      "prepStmtCacheSize": "250",
      "prepStmtCacheSqlLimit": "2048",
      "useServerPrepStmts": "true"
    }
  },
  "secrets": {
    "key": "value"
  },
  "origins": {
    "allowed": [
      "https://*:*", "http://*:*"
    ]
  },
  "admin": {
    "email": ""
  },
  "plugin": {
    "coreInstallMode": "Once"
  }
}

Configuration Sections

Environment (env)

{
  "env": "DEV"
}
FieldTypeDefaultDescription
envstring"DEV"Environment identifier (e.g., DEV, STAGING, PROD)

Host (host)

{
  "host": "http://localhost:7071"
}
FieldTypeDefaultDescription
hoststring"http://localhost:7071"The base URL where the engine is hosted

Data Source (datasource)

Database connection configuration for PostgreSQL.

{
  "datasource": {
    "url": "",
    "host": "localhost",
    "port": 5432,
    "user": "postgres",
    "password": "secret",
    "database": "bshengine",
    "driverClassName": "org.postgresql.Driver",
    "pool": { ... },
    "query": { ... },
    "properties": { ... }
  }
}

Main Fields

FieldTypeDefaultRequiredDescription
urlstring-Yes*Full JDBC URL (e.g., jdbc:postgresql://host:port/db)
hoststring-Yes*Database host
portnumber5432NoDatabase port
userstring-YesDatabase username
passwordstring-YesDatabase password
databasestring-Yes*Database name
driverClassNamestring"org.postgresql.Driver"NoJDBC driver class

You can provide either a full url OR the combination of host, port, and database. If url is empty, the engine constructs it from the individual fields.

Connection Pool (pool)

{
  "pool": {
    "maximumPoolSize": 10,
    "minimumIdle": 5,
    "idleTimeout": 300000,
    "connectionTimeout": 30000,
    "maxLifetime": 1800000
  }
}
FieldTypeDefaultDescription
maximumPoolSizenumber10Maximum number of connections in the pool
minimumIdlenumber5Minimum number of idle connections to maintain
idleTimeoutnumber300000Max time (ms) a connection can sit idle before removal (5 min)
connectionTimeoutnumber30000Max time (ms) to wait for a connection from pool (30 sec)
maxLifetimenumber1800000Max lifetime (ms) of a connection in the pool (30 min)

Query Settings (query)

{
  "query": {
    "queryTimeout": 30,
    "fetchSize": 100
  }
}
FieldTypeDefaultDescription
queryTimeoutnumber30Query timeout in seconds
fetchSizenumber100Number of rows fetched per database round-trip

Connection Properties (properties)

{
  "properties": {
    "cachePrepStmts": "true",
    "prepStmtCacheSize": "250",
    "prepStmtCacheSqlLimit": "2048",
    "useServerPrepStmts": "true"
  }
}

These are PostgreSQL-specific performance optimizations for prepared statement caching.

Secrets (secrets)

Store sensitive credentials that can be referenced elsewhere in the system using the env: prefix.
for built-in secret, read this

CORS Origins (origins)

Configure allowed origins for Cross-Origin Resource Sharing (CORS).

{
  "origins": {
    "allowed": [
      "https://yourdomain.com",
      "http://localhost:3000"
    ]
  }
}
FieldTypeDefaultDescription
allowedstring[]["https://*:*", "http://*:*"]List of allowed origins

The default allows all origins. For production, specify exact domains.

Admin (admin)

Initial admin user configuration. Required for first-time setup.

{
  "admin": {
    "email": "admin@example.com"
  }
}
FieldTypeRequiredDescription
emailstringYesAdmin user email for initial setup
passwordstringNoAdmin password (optional, will be auto-generated)

Plugin (plugin)

Plugin system configuration.

{
  "plugin": {
    "coreInstallMode": "Once"
  }
}
FieldTypeDefaultOptionsDescription
coreInstallModestring"Once"Once, AlwaysHow core plugins are installed
  • Once: Core plugins are installed only on first startup (recomanded in production)
  • Always: Core plugins are reinstalled on every startup (useful for development)

Complete Example

bshconfig.json
{
  "env": "PROD",
  "host": "https://api.yourapp.com",
  "datasource": {
    "host": "db.yourapp.com",
    "port": 5432,
    "user": "bsh_user",
    "password": "secure-password-here",
    "database": "bshengine_prod",
    "driverClassName": "org.postgresql.Driver",
    "pool": {
      "maximumPoolSize": 20,
      "minimumIdle": 5,
      "idleTimeout": 300000,
      "connectionTimeout": 30000,
      "maxLifetime": 1800000
    },
    "query": {
      "queryTimeout": 30,
      "fetchSize": 100
    },
    "properties": {
      "cachePrepStmts": "true",
      "prepStmtCacheSize": "250",
      "prepStmtCacheSqlLimit": "2048",
      "useServerPrepStmts": "true"
    }
  },
  "secrets": {
    "key": "value"
  },
  "origins": {
    "allowed": [
      "https://yourapp.com",
      "https://www.yourapp.com"
    ]
  },
  "admin": {
    "email": "admin@yourapp.com"
  },
  "plugin": {
    "coreInstallMode": "Once"
  }
}

Setting Up the Configuration

Stringify your JSON configuration and set it as an environment variable:

export BSH_CONFIG='{"env":"PROD","datasource":{...},...}'

Validation

The engine validates the configuration at startup. Required fields:

  1. datasource.url (or host + database combination)
  2. datasource.user
  3. datasource.password
  4. admin.email

If any required field is missing, the engine will fail to start with a SERVICE_UNAVAILABLE error indicating which fields are missing.
Make sure to read the logs for these info

Security Best Practices

Follow these security guidelines when configuring your BSH Engine instance.

  1. Never commit your actual configuration with real credentials to version control
  2. Use environment variables or secret management tools in production
  3. Restrict CORS origins to specific domains in production
  4. Use strong JWT secrets (at least 256 bits)
  5. Use app-specific passwords for email services
  6. Rotate credentials regularly
EnvironmentRegister