Skip to main content

Deploy a StackBob On-Prem Bridge

How-to guide · On-Prem Bridge

Written by Agent Bob

To connect StackBob.ai to an app that is hosted inside your private network and is not accessible from the internet, deploy StackBob On-Prem Bridge. The bridge runs as a container in your network and connects outbound to StackBob.ai. StackBob NCAP™ can then reach the app without inbound firewall rules or a VPN. Apps that are accessible from the internet connect through a Direct Internet Connection instead.

In this guide, you select On-Prem Bridge as the app’s connection type and generate an installation command in StackBob.ai. Then verify the bridge image, and run the bridge container on a host in your network. When you finish, the bridge is connected to StackBob.ai, and you can continue with the NCAP™ Integration setup for the app.

This guide uses Atlassian Suite as the example managed app. The steps are the same for any managed app. For the bridge architecture and security controls, see StackBob On-Prem Bridge architecture and security article


Roles

A bridge deployment involves two roles. One person can hold both.

Role

Responsibilities

Steps

StackBob.ai admin

Holds the Org Admin role in StackBob.ai. Selects the connection type, generates the installation command, and confirms the connection.

1, 2, 5

Infrastructure administrator

Has administrative access to a host in the network where the app runs. Verifies the image and runs the bridge.

3, 4

⚠️ If the roles are held by different people, the StackBob.ai admin needs to send the installation command to the infrastructure administrator through a secure channel (as it contains the secret token), together with a link to this article.


Prerequisites

In StackBob.ai

In your network

  • A host that can reach the managed app and run Docker containers, such as a Linux server or virtual machine.

  • Permission to run Docker containers on the host.

  • Sigstore cosign, installed on the host or on a workstation that can reach public.ecr.aws.

  • The network access listed in the following table.

Direction

Destination

Port

Purpose

Outbound

bridge.stackbob.ai

TCP 443

Tunnel connection to StackBob.ai

Internal

Managed app host

App port, such as 443

Connections to the app

Internal

Internal DNS

53

Resolving the app hostname

Outbound, during installation and upgrades

public.ecr.aws

TCP 443

Image download. Not required if you use an internal registry mirror.

Inbound

—

—

None

✅ For production deployments, StackBob.ai recommends a dedicated Linux server or virtual machine, placed in a network segment that can reach only DNS and the managed app hosts.

ℹ️ If your environment cannot run Docker containers, for example a Windows Server host, contact StackBob.ai support. We will work with you to provide a suitable deployment option.


Step 1. Select On-Prem Bridge as the connection type in StackBob.ai

Performed by the StackBob.ai admin.

  1. In StackBob.ai, open the managed app. The app initial status is Setup Required.

  2. Under Select App Connection Type, select On-Prem Bridge, and then select Set Up Sync.


Step 2. Create the bridge in StackBob.ai and copy the installation command

Performed by the StackBob.ai admin.

  1. Under Select On-Prem Connection, select New StackBob On-Prem Bridge, and then select Continue.

  2. Under Name the Bridge, keep the default name or select the pencil icon to change it. The default name combines your organization name and the app name. The bridge will appear under this name in your StackBob.ai Organization Settings.
    ​

  3. Under Run the Docker container using the installation command, select copy.

    ⚠️ The installation command contains the secret token for this bridge node. Share it only through a secure channel, and do not store it in tickets, chat messages, or shared documents.

  4. Connection Status shows Bridge Pending and will automatically change to Bridge Established when the bridge connects. Until then, Continue option is unavailable.


Step 3. Verify the bridge image

Performed by the infrastructure administrator.

Docker does not verify image signatures when it pulls an image. Before you run the bridge, confirm that the image was built and signed by StackBob.ai’s CI pipeline.

  1. Note the version tag at the end of the installation command, such as 2.1.0.

  2. Run the following command, replacing <version> with that tag:
    ​bash

    cosign verify \ 
    --certificate-oidc-issuer https://gitlab.com \
    --certificate-identity 'https://gitlab.com/mindswede/stackoon//.gitlab-ci.yml@refs/heads/main' \
    public.ecr.aws/p2d9q2r4/stackbob-bridge:<version>

  3. Confirm that the command completes without errors.

⚠️ If verification fails, do not run the image. Contact StackBob.ai support.

ℹ️ To run the bridge from an internal registry, mirror the verified image with cosign copy. Then replace the image reference in the installation command with your registry path. Do not mirror with docker pull and docker push, because they do not copy signatures, and the mirrored image cannot be verified.

bash

cosign copy public.ecr.aws/p2d9q2r4/stackbob-bridge:<version> \   
registry.example.com/stackbob-bridge:<version>

⚠️ If the container stops or reconnects repeatedly, see Troubleshoot StackBob On-Prem Bridge connections.


Step 4. Run the bridge container

Performed by the infrastructure administrator.


​1. On the host, run the installation command from step 2. With Podman, use podman in place of docker.

bash

docker run -d --restart=always --network host \ 
-e STACKBOB_TOKEN=<token> \
public.ecr.aws/p2d9q2r4/stackbob-bridge:<version>

Part

Purpose

-d

Runs the container in the background

--restart=always

Restarts the bridge after a host reboot or a failure

--network host

Uses the host’s DNS and network routes to reach the app

-e STACKBOB_TOKEN=…

Provides the bridge node’s token

2. Confirm that the container is running. The docker run command prints a container ID. To view the bridge’s logs, run docker logs <container-id>.

⚠️ Membership in the docker group on the host is equivalent to root access. Restrict Docker access to the administrators who manage the bridge.

ℹ️ On macOS and on Windows 10 or 11, the container runs in the Linux virtual machine provided by Docker Desktop, Colima, OrbStack, or Podman. Confirm that the app hostname and your internal DNS are reachable from that environment.

Optional settings

Add the following settings to the installation command as your environment requires:

  • Corporate proxy. If outbound traffic must pass through a proxy, set HTTPS_PROXY. The proxy must permit WebSocket traffic over CONNECT to bridge.stackbob.ai:443.

  • TLS inspection. StackBob.ai recommends excluding bridge.stackbob.ai from TLS inspection. If inspection cannot be bypassed, mount your inspection CA certificate and set SSL_CERT_FILE. The CA is added to the public root certificates.

  • Token file. To keep the token out of environment variables, store it in a file and set STACKBOB_TOKEN_FILE in place of STACKBOB_TOKEN. The file must contain only the token. It must also be readable by the container’s non-root user (UID 65532).

  • JSON logs. To forward logs to a SIEM, set STACKBOB_LOG_FORMAT=json.

  • Debug logging. For troubleshooting, set STACKBOB_DEBUG=1 to log each relayed connection.

Example with a proxy, an inspection CA, a token file, and JSON logs:
​bash

docker run -d --restart=always --network host \   
-e HTTPS_PROXY=http://proxy.example.com:8080 \
-v /etc/stackbob/corp-ca.pem:/etc/stackbob/corp-ca.pem:ro \
-e SSL_CERT_FILE=/etc/stackbob/corp-ca.pem \
-v /etc/stackbob/token:/etc/stackbob/token:ro \
-e STACKBOB_TOKEN_FILE=/etc/stackbob/token \
-e STACKBOB_LOG_FORMAT=json \
public.ecr.aws/p2d9q2r4/stackbob-bridge:<version>

⚠️ If Connection Status remains Bridge Pending, see Troubleshoot StackBob On-Prem Bridge connections.


Step 5. Confirm the connection in StackBob.ai

Performed by the StackBob.ai admin.

  1. Return to the app page in StackBob.ai. When the bridge connects, Connection Status changes from Bridge Pending to Bridge Established.

  2. Select Continue to proceed with the NCAP™ Integration setup for the app.

All your bridges are also listed under Settings › Organization Settings › Integrations › On-Prem Bridges. It appears as an On-Prem Bridge Group, with its nodes, status, and the number of connected apps. The node you deployed in this guide is the Primary Node.


Add a backup node (optional)

A backup node can run on a second host and provide failover for the bridge. StackBob.ai checks the nodes of a bridge group in order and uses the first node that can reach the app. If the primary host becomes unavailable, traffic moves to a backup node automatically. A bridge group can include more than one backup node.

The second host must meet the same prerequisites as the primary host. It needs network access to the app, to your internal DNS, and to bridge.stackbob.ai.

✅ To get the most from failover, place the backup node in a different failure domain from the primary node, such as another hypervisor, rack, or availability zone.

​
​Steps a, b, c and e are performed by the StackBob.ai admin. Step d is performed by the infrastructure administrator.


a. In StackBob.ai go to Settings › Organization Settings › Integrations › On-Prem Bridges.


b. In the row for the bridge group, select more actions (⋮), and then select Add backup node.
c. In the Add Backup Node panel that opens, under Run the Docker container using the installation command, select Generate secret command, and then copy the installation command.
​

⚠️ The command contains the secret token for the backup node. Share it only through a secure channel. Do not reuse the Primary Node’s installation command on the second host, because each node has its own token.

d. On the second host, complete Verify the bridge image and Run the bridge container (as described in Step 3 nd Step 4), using the backup node’s installation command.

e. In StackBob.ai on the On-Prem Bridges tab, confirm that the backup node’s status changes from Bridge Pending to Bridge Established.
​


Terminate a node or a bridge group

Terminating a backup node revokes that node’s token. Terminating a bridge group revokes the tokens of all its nodes.

Removing a node or a bridge group takes two actions, which can be done in either order. The StackBob.ai admin terminates the node or group in StackBob.ai, which revokes its token. The infrastructure administrator removes the bridge container from the host. If you suspect that a node’s installation command or token has been exposed, terminate the node in StackBob.ai immediately.

Terminate a single node

Terminate a single node when you no longer need it, for example a backup node on a decommissioned host, or when the node’s installation command has been exposed.

  1. Go to Settings › Organization Settings › Integrations › On-Prem Bridges.

  2. In the row for the node, select more actions menu (⋮), and then select Terminate Node.

  3. Remove the bridge container from the node’s host, as described in Remove the bridge container below.

The other nodes in the bridge group continue to serve the connected apps.

⚠️ If no other node in the group has the status Bridge Established, StackBob NCAP™ can no longer reach the apps that were connected through the bridge.

Terminate the entire bridge group

  1. Go to Settings › Organization Settings › Integrations › On-Prem Bridges.

  2. In the row for the bridge group, select ⋮, and then select Terminate Entire Group.

  3. Remove the bridge container from each host that ran a node of the group, as described in the next section.

Remove the bridge container

After you terminate a node or a bridge group, remove the bridge container from each affected host. To find the container ID, run docker ps.

bash

docker rm -f <container-id>

ℹ️ After termination, the bridge container exits with code 3 because its token is revoked. The container was started with --restart=always, so Docker keeps restarting it until it is removed.

ℹ️ Stopping the container on the host disconnects the node immediately but does not revoke its token. To revoke access permanently, terminate the node or the bridge group in StackBob.ai.


Next steps

Did this answer your question?