Servers

Servers represent the physical or virtual machines where your Docker containers run — BRIDGEPORT connects to them via SSH or Docker socket to deploy, monitor, and manage services.

Quick Start

Get a server managed by BRIDGEPORT in 3 steps:

1. Configure SSH key for your environment (one-time setup):

   • Go to Configuration > Environment Settings and upload your SSH private key.

2. Add a server:

   • Go to Operations > Servers and click Add Server.
   • Enter a name, hostname (private IP or FQDN), and optional tags.

3. Discover containers:

   • On the server detail page, click Discover to auto-import all running Docker containers as services.

---

How It Works

BRIDGEPORT manages servers through two connection modes. Each server belongs to one environment and inherits that environment’s SSH key.

flowchart TD
    A[BRIDGEPORT] -->|SSH connection| B[Remote Server]
    A -->|Docker socket| C[Host Machine]
    B --> D[Docker Daemon]
    C --> E[Docker Daemon]
    D --> F[Containers]
    E --> G[Containers]

    style A fill:#4f46e5,color:#fff
    style B fill:#1e293b,color:#fff
    style C fill:#1e293b,color:#fff

SSH mode (default): BRIDGEPORT connects to the server over SSH using the environment’s private key, then runs Docker commands remotely. This is the standard mode for remote servers.

Socket mode: BRIDGEPORT connects directly to the Docker daemon via the local Docker socket (/var/run/docker.sock). This is for the host machine when BRIDGEPORT itself runs as a Docker container.

---

Step-by-Step Guide

Adding a Server

UI:

1. Navigate to Operations > Servers.
2. Click Add Server.
3. Fill in the form:
   • Name — descriptive identifier (e.g., app-api-staging, web-prod-1)
   • Hostname — private IP or FQDN (e.g., 10.20.10.3, server.example.com)
   • Public IP — optional reserved/public IP for display purposes
   • Tags — optional labels for organization (e.g., web, api, database)
4. Click Create.

API:

POST /api/environments/:envId/servers
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "app-api-staging",
  "hostname": "10.20.10.3",
  "publicIp": "203.0.113.50",
  "tags": ["api", "staging"]
}

Response (200):

{
  "server": {
    "id": "clxyz...",
    "name": "app-api-staging",
    "hostname": "10.20.10.3",
    "publicIp": "203.0.113.50",
    "tags": "[\"api\",\"staging\"]",
    "status": "unknown",
    "dockerMode": "ssh",
    "metricsMode": "disabled",
    "environmentId": "clenv..."
  }
}

Server names must be unique within an environment. If a name is already taken, the server returns 409 Conflict.

Listing and Inspecting Servers

List servers (paginated):

GET /api/environments/:envId/servers?limit=25&offset=0

Pass ?include=services-count to add a _count: { services } field to each server — useful for env-detail dashboards that need per-server service counts without loading the full service list.

Get a single server:

GET /api/servers/:id

By default, this returns just the server row (fast, no joins). Pass ?include=services to nest the server’s services and their container images — use this on the server-detail page where the nested data is needed.

Inspect drift across every deployment on a server:

GET /api/servers/:id/drift

Read-only (viewer-accessible): diffs BRIDGEPORT’s stored view against the actual host state (compose path/content, image digest, exposed ports, attached config files, and managed env vars) for every deployment on this server. It only runs docker inspect and file reads — it never mutates host state. See Drift Detection in the Services guide for the full response shape and per-field semantics.

SSH Key Configuration

Every environment has one SSH private key that all servers in that environment share. The key is encrypted at rest using AES-256-GCM.

Step 1: Generate or locate your SSH key pair.

# Generate a new key pair (if you don't have one)
ssh-keygen -t ed25519 -C "bridgeport-staging" -f ~/.ssh/bridgeport_staging

Step 2: Add the public key to your servers.

# Copy public key to each server
ssh-copy-id -i ~/.ssh/bridgeport_staging.pub root@10.20.10.3

Step 3: Upload the private key to BRIDGEPORT.

Navigate to Configuration > Environment Settings > General and paste your private key, or use the API:

PUT /api/environments/:envId/ssh
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "sshPrivateKey": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----",
  "sshUser": "root"
}

Step 4: Verify the connection.

On the server detail page, click the Health Check button. A successful check confirms SSH connectivity:

{
  "status": "healthy",
  "container": {
    "state": "running",
    "running": true
  }
}

Note

The SSH user defaults to root but can be changed per environment in General Settings. The user must have permission to run docker commands.

Deleting an SSH key (DELETE /api/environments/:envId/ssh) removes connectivity to all servers in that environment. Health checks, deployments, and container discovery will fail until a new key is configured.

Docker Mode Setup

Each server has a dockerMode that determines how BRIDGEPORT communicates with Docker:

Mode	How it connects	When to use
ssh (default)	SSH into server, run docker commands	Remote servers
socket	/var/run/docker.sock directly	Host machine (BRIDGEPORT is a container)

Changing Docker mode:

PATCH /api/servers/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "dockerMode": "socket"
}

Tip

If BRIDGEPORT runs as a Docker container on the same machine it manages, use socket mode for that server. This avoids SSH overhead and does not require an SSH key.

Server Health Monitoring

Health checks verify that BRIDGEPORT can connect to the server and that Docker is responsive.

Manual health check:

Click the health check icon on the server card, or:

POST /api/servers/:id/health
Authorization: Bearer <token>

This connects via SSH (or socket), runs Docker commands to verify the daemon is responsive, and updates the server’s status to healthy or unhealthy.

Automated health checks:

When monitoring is enabled for the environment, BRIDGEPORT runs server health checks on a configurable interval (default: 60 seconds). Configure the interval in Environment Settings > Monitoring > Server Health Interval.

Metrics Mode Selection

Each server can collect system metrics in one of three modes. Use this decision tree to pick the right one:

flowchart TD
    A{Need server metrics?} -->|No| B[disabled]
    A -->|Yes| C{BRIDGEPORT can SSH<br>into the server?}
    C -->|Yes| D{Need container-level<br>detail + processes?}
    C -->|No| B
    D -->|Basic is fine| E[ssh]
    D -->|Yes, I want everything| F[agent]

    style B fill:#374151,color:#fff
    style E fill:#2563eb,color:#fff
    style F fill:#059669,color:#fff

Mode	Metrics collected	How	Requirements
disabled	None	—	—
ssh	CPU, memory, disk, load, swap, TCP, FDs	BRIDGEPORT polls via SSH on a schedule	SSH key configured
agent	SSH metrics + container stats, top processes, TCP/cert checks	Agent binary pushes to BRIDGEPORT	Agent auto-deployed via SSH

Changing metrics mode:

PATCH /api/servers/:id/metrics-mode
Authorization: Bearer <token>
Content-Type: application/json

{
  "mode": "agent"
}

When switching to agent mode, BRIDGEPORT automatically deploys the monitoring agent binary to the server via SSH. When switching away from agent, the agent is removed.

Note

Agent deployment requires SSH access. The agent runs as a background service on the server and pushes metrics to BRIDGEPORT at a regular interval. See Agent Reference for details.

Container Discovery

Discovery scans a server’s Docker daemon and automatically creates service records for every running container.

Manual discovery:

Click Discover on the server detail page, or:

POST /api/servers/:id/discover
Authorization: Bearer <token>

Response:

{
  "services": [
    {
      "id": "clsvc1...",
      "name": "app-api",
      "containerName": "app-api",
      "imageTag": "v2.1.0",
      "status": "running"
    }
  ],
  "missing": ["old-service"]
}

The services array contains newly discovered or updated services. The missing array lists previously tracked services whose containers were not found during this scan (their discoveryStatus is set to missing).

Note

Discovery matches existing services by containerName, not by name. This means you can freely rename a service’s display name (e.g. keycloak → keycloak-eu-prod) without breaking discovery — as long as containerName still matches the Docker container_name field in your compose file.

Automated discovery:

When monitoring is enabled, discovery runs on a configurable interval (default: 5 minutes). Adjust it in Environment Settings > Monitoring > Discovery Interval.

Tip

Discovery creates a ContainerImage record for each unique image it finds. If a matching image already exists in the environment, the service is linked to it automatically.

Creating Services Manually

You can create services before the container exists on the server. This is useful when preparing a deployment ahead of time.

1. Navigate to the server detail page.
2. Click Create Service.
3. Fill in:
   • Name — service identifier
   • Container Name — the Docker container name
   • Container Image — select an existing image or create one
   • Image Tag — tag to deploy (default: latest)
   • Compose Path — optional path to docker-compose.yml on the server
4. Click Create.

See Services for the full guide on managing services after creation.

---

Host Server Mode

When BRIDGEPORT runs as a Docker container, it can manage the host machine directly. BRIDGEPORT detects the Docker gateway IP and can register the host as a special server with serverType: "host" and dockerMode: "socket".

Check host info:

GET /api/environments/:envId/host-info
Authorization: Bearer <token>

Register the host:

POST /api/environments/:envId/servers/register-host
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "host"
}

Host servers connect via Docker socket and do not require SSH keys. They support all the same operations as remote servers (discovery, deployments, health checks).

---

Configuration Options

Server-Level Settings

Setting	API Field	Options	Default	Description
Docker Mode	dockerMode	ssh, socket	ssh	How to connect to Docker daemon
Metrics Mode	metricsMode	disabled, ssh, agent	disabled	How server metrics are collected
Server Type	serverType	remote, host	remote	Whether server is remote or the Docker host

Environment-Level Settings (Affect All Servers)

Setting	Module	Default	Description
SSH User	General	root	SSH username for all servers in this environment
Default Docker Mode	Operations	ssh	Docker mode applied to new servers
Default Metrics Mode	Operations	disabled	Metrics mode applied to new servers
Server Health Interval	Monitoring	60000ms	How often to check server health
Discovery Interval	Monitoring	300000ms	How often to scan for containers
Metrics Interval	Monitoring	300000ms	How often to collect SSH metrics

---

Troubleshooting

Health check fails with “SSH connection refused”

• Verify the environment has an SSH key configured: GET /api/environments/:envId/ssh
• Confirm the SSH user has access: ssh -i key root@hostname
• Check the server’s firewall allows port 22

Health check fails with “Docker daemon not responding”

• Verify Docker is running on the server: systemctl status docker
• Confirm the SSH user can run Docker: docker ps
• For socket mode, ensure BRIDGEPORT’s container has the Docker socket mounted

Container discovery returns empty results

• Verify Docker is running and has containers: docker ps on the server
• Check that the SSH user has permission to list containers
• For socket mode, ensure /var/run/docker.sock is mounted in BRIDGEPORT’s container

“Server already exists” (409) Server names must be unique within an environment. Choose a different name or delete the existing server first.

Agent deploy fails

• SSH must be working (test with a health check first)
• The server needs internet access to download the agent binary, or BRIDGEPORT serves it
• Check agent deploy logs: Monitoring > Agents & SSH

Metrics not appearing after enabling SSH mode

• Confirm the SSH user can run system commands (uptime, free, df)
• Check the metrics interval in Environment Settings > Monitoring
• Verify monitoring is enabled for the environment (master toggle)

---

Related

• Server Bootstrap — one-click Docker + agent + sysctl + swap setup for new Ubuntu/Debian hosts
• Services — managing Docker containers on servers
• Environments — SSH key and per-module settings
• Monitoring Quick Start — setting up metrics collection
• Agent Reference — agent installation and configuration
• Environment Settings Reference — all server-related settings