Environment Settings Reference

Every environment in BRIDGEPORT has per-environment settings organized into five modules: General, Monitoring, Operations, Data, and Configuration. Settings are created with defaults when an environment is created and can be adjusted in Environment Settings (admin only).

Overview

Environment settings allow you to configure each environment independently. For example, you might want:

More frequent health checks in production than in staging
Agent-based metrics in production, SSH-based in staging
Backup downloads enabled only in staging

Settings are managed through the UI at Environment > Settings (admin access required) or via the API.

API

All settings endpoints require admin authentication.

Get settings for a module:

GET /api/environments/:envId/settings/:module

Where :module is one of: general, monitoring, operations, data, configuration.

Update settings:

PATCH /api/environments/:envId/settings/:module
Content-Type: application/json

{
  "sshUser": "deploy",
  "enabled": true
}

Only include the fields you want to change. Unknown fields are rejected. Invalid values return a 400 error with details.

Reset to defaults:

POST /api/environments/:envId/settings/:module/reset

General Settings

SSH and connectivity configuration.

Setting	Type	Default	Description
`sshUser`	`string`	`"root"`	Default SSH username for connecting to servers in this environment

Monitoring Settings

Per-metric collection toggles. The Monitoring tab now exposes only the collect* toggles below.

Monitoring cadence and retention are global, not per-environment. Earlier releases had per-environment monitoring fields (enabled, serverHealthIntervalMs, serviceHealthIntervalMs, discoveryIntervalMs, metricsIntervalMs, updateCheckIntervalMs, backupCheckIntervalMs, metricsRetentionDays, healthLogRetentionDays, bounceThreshold, bounceCooldownMs). These were silently ignored by the SSH scheduler and have been removed:

Collection cadence is set globally by the SCHEDULER_* environment variables — see Configuration Reference → Scheduler.
Retention (server/service metrics, health logs) is global — METRICS_RETENTION_DAYS (env var) and the System Settings retention knobs.
Alert bounce thresholds now live on Notification Types (Admin → Notifications), not per environment.

Metrics Collection

Setting	Type	Default	Range	Description
`collectCpu`	`boolean`	`true`	—	Collect CPU usage metrics
`collectMemory`	`boolean`	`true`	—	Collect memory usage metrics
`collectSwap`	`boolean`	`true`	—	Collect swap usage metrics
`collectDisk`	`boolean`	`true`	—	Collect disk usage metrics
`collectLoad`	`boolean`	`true`	—	Collect system load averages
`collectFds`	`boolean`	`true`	—	Collect file descriptor counts
`collectTcp`	`boolean`	`true`	—	Collect TCP connection metrics
`collectProcesses`	`boolean`	`true`	—	Collect running process count
`collectTcpChecks`	`boolean`	`true`	—	Run TCP connectivity checks on services
`collectCertChecks`	`boolean`	`true`	—	Check TLS certificate expiry on services

Operations Settings

Defaults for new servers and environment-wide operational behavior.

Setting	Type	Default	Options	Description
`defaultDockerMode`	`string`	`"ssh"`	`ssh`, `socket`	Default Docker daemon connection method for new servers
`defaultMetricsMode`	`string`	`"disabled"`	`disabled`, `ssh`, `agent`	Default metrics collection mode for new servers
`autoPruneImages`	`boolean`	`false`	—	Run `docker image prune` automatically after every deploy to the affected server, and weekly on all healthy servers in this environment
`pruneImagesMode`	`string`	`"dangling"`	`dangling`, `all`	Which images are pruned. `dangling` removes only untagged layers (safe default). `all` removes any image not used by a running container, including rollback targets — use with care.
`autoManageCompose`	`boolean`	`false`	—	When a deployment has no compose file path yet, let BRIDGEPORT set it to the generated compose file on first deploy. A compose path that is already set (by an operator, the API, or a previous import) is never overwritten regardless of this setting.

Compose path management (autoManageCompose). BRIDGEPORT never rewrites a deployment’s composePath once it is set. With this setting off (the default), a deployment whose composePath is still null is deployed by restarting its container directly rather than via a generated compose file — point it at a compose file manually (or enable this setting) to deploy through docker compose. With it on, the first deploy of a path-less deployment writes a generated compose file and records its path. Every automatic composePath change is written to the audit log with details.source (generator or terraform-import). Generated and template-authored compose files are validated before deploy: the compose document must define a service keyed exactly on the deployment’s containerName, otherwise the deploy is refused with an actionable error instead of failing mid-rollout. Shared compose files that back multiple deployments are validated against the file already on disk and are never rewritten.

Data Settings

Database backup and monitoring defaults.

Backup Settings

Setting	Type	Default	Description
`allowBackupDownload`	`boolean`	`false`	Allow users to download database backups from the UI. Enable for development environments; disable in production for security.

Database Monitoring Defaults

Setting	Type	Default	Range	Description
`defaultMonitoringEnabled`	`boolean`	`false`	—	Enable monitoring by default when adding new databases
`defaultCollectionIntervalSec`	`integer`	`300` (5 min)	60 — 3,600	Default metrics collection interval for new databases (seconds)

Configuration Settings

Security and config-scanner settings for this environment.

Security

Setting	Type	Default	Description
`allowSecretReveal`	`boolean`	`true`	Allow users to reveal secret values in the UI. When disabled, secrets are write-only — users can set values but never view them.

Config Scanner

Controls sensitivity of the config file scanner that detects hardcoded values and suggests promoting them to secrets or vars.

Setting	Type	Default	Range	Description
`scanMinLength`	`integer`	`6`	1 — 100	Minimum value length to consider. Shorter values are ignored.
`scanEntropyThreshold`	`integer`	`25`	0 — 80	Shannon entropy threshold stored as ×10 (25 = 2.5 bits/char). Values below this are filtered out as low-entropy.

Notification Settings

Per-environment notification routing. Lives outside the module registry because the channel options are dynamic (Slack channels are defined in Admin > Slack). Configured under Settings > Notifications for each environment.

Setting	Type	Default	Description
`slackChannelId`	`string \| null`	`null` (inherit)	This environment’s Slack channel. Used two ways: (1) for a type routed to more than one channel, the override collapses the fan-out and sends only to this channel (per-environment alert splitting); (2) for an unrouted type, it stands in for the global default. A type routed to exactly one channel is unaffected and reaches that channel from every environment. When `null`, notifications fall back to the global default channel (the one marked `isDefault`). See notifications guide → Per-Environment Channel Override.

API:

GET    /api/environments/:envId/settings/notifications
PATCH  /api/environments/:envId/settings/notifications     # { "slackChannelId": "<id>" | null }
POST   /api/environments/:envId/settings/notifications/test

GET returns { settings, channels, defaultChannel } — channels is the list of enabled Slack channels (so the UI can render a dropdown), and defaultChannel is the global default (so the UI can show “Inherits default: #channel-name”). The test endpoint sends a Slack test message through the resolved channel (override if set, otherwise the global default).

System Settings — Global system-wide settings (admin only)
Agent Reference — How the agent uses monitoring settings
Plugin Reference — Database type monitoring queries
API Reference — Full API endpoint documentation