Configuration Components
Use the cards below to understand each top-level configuration component quickly: key name, whether it is required, default value, and detailed options.
Selects cookie security behavior for auth tokens and is reported in engine status.
{
"env": "Dev"
}| Field | Type | Default | Description |
|---|---|---|---|
env | string | "Dev" (implicit) | Controls Secure and SameSite on bsh_access_token and bsh_refresh_token cookies. |
Allowed values (case-insensitive):
| Value | Cookie Secure | Cookie SameSite | Typical use |
|---|---|---|---|
Dev | false | Lax | Local or HTTP development; same-site frontend and API |
Prod | true | Lax | HTTPS production; same-site frontend and API |
CrossSiteDev | false | None | Cross-origin development (frontend and API on different sites) |
CrossSiteProd | true | None | HTTPS production with cross-site frontend and API |
If env is missing or unrecognized, the engine defaults to Dev.
Database connection configuration for PostgreSQL, including connection, pool, and query tuning settings.
{
"datasource": {
"host": "localhost",
"port": 5432,
"user": "postgres",
"password": "secret",
"database": "bshengine",
"driverClassName": "org.postgresql.Driver",
"pool": { ... },
"query": { ... },
"properties": { ... }
}
}
}Main Fields
| Field | Type | Default | Required | Description |
|---|---|---|---|---|
host | string | - | Yes | Database host |
port | number | 5432 | No | Database port |
user | string | - | Yes | Database username |
password | string | - | Yes | Database password |
database | string | - | Yes | Database name |
driverClassName | string | "org.postgresql.Driver" | No | JDBC driver class |
The production setup uses host, port, and database directly.
Connection Pool (pool)
{
"datasource": {
"pool": {
"maximumSize": 10,
"minimumIdle": 5,
"idleTimeout": 300000,
"connectionTimeout": 30000,
"maxLifetime": 1800000
}
}
}| Field | Type | Default | Description |
|---|---|---|---|
maximumSize | number | 10 | Maximum number of connections in the pool |
minimumIdle | number | 5 | Minimum number of idle connections to maintain |
idleTimeout | number | 300000 | Maximum idle time in milliseconds before removal (5 minutes) |
connectionTimeout | number | 30000 | Maximum wait time in milliseconds for a pool connection (30 seconds) |
maxLifetime | number | 1800000 | Maximum connection lifetime in milliseconds (30 minutes) |
Query Settings (query)
{
"datasource": {
"query": {
"queryTimeout": 30,
"fetchSize": 100
}
}
}| Field | Type | Default | Description |
|---|---|---|---|
queryTimeout | number | 30 | Query timeout in seconds |
fetchSize | number | 100 | Number of rows fetched per database round trip |
Connection Properties (properties)
{
"datasource": {
"properties": {
"cachePrepStmts": "true",
"prepStmtCacheSize": "250",
"prepStmtCacheSqlLimit": "2048",
"useServerPrepStmts": "true"
}
}
}These are PostgreSQL-oriented performance options for prepared statement caching.
Stores sensitive credentials that can be referenced elsewhere using the env: prefix.
For built-in secrets, see Settings secrets.
{
"secrets": {
"mailing": {
"provider": "gmail",
"email": "your@email.com",
"from": "noreply@yourapp.com",
"fromName": "BSH Engine",
"password": "mail-app-password"
},
"cloudinary": {
"apiKey": "your-api-key",
"apiSecret": "your-api-secret",
"cloudName": "your-cloud-name",
"folder": "uploads"
},
"jwt": {
"secret": "your-long-random-jwt-secret"
}
},
}Configure allowed origins for Cross-Origin Resource Sharing (CORS).
{
"origins": {
"allowed": [
"https://yourdomain.com",
"https://admin.yourdomain.com"
]
}
}| Field | Type | Required | Description |
|---|---|---|---|
allowed | string[] | Yes | List of allowed origins to be used in the CORS policy. |
Patterns and wildcards like https://* or 127.0.0.1:* are not accepted.
You must specify each allowed site exactly.
There is no default value; this field is required.
Application-level variables that can be reused by templates, flows, or integrations.
{
"variables": {
"host": "https://api.yourapp.com",
"key": "value"
}
}| Field | Type | Required | Description |
|---|---|---|---|
key | string | No | Variable name |
value | string | No | Variable value |
Initial admin user configuration. Required for first-time setup.
{
"admin": {
"email": "admin@example.com"
}
}| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Admin user email for initial setup |
password | string | No | Admin password (optional; auto-generated if omitted) |
Plugin system configuration.
{
"plugin": {
"coreInstallMode": "Once"
}
}| Field | Type | Default | Options | Description |
|---|---|---|---|---|
coreInstallMode | string | "Once" | Once, Always | How core plugins are installed |
Once: Core plugins are installed only on first startup (recommended in production).Always: Core plugins are reinstalled on every startup (useful in development).
