Upgrade to Bridge v2

Stop v1 and back up its volume

Stop the v1 container:

docker compose down

Archive the volume. Replace bridge_bridge-data with your volume name:

docker run --rm -v bridge_bridge-data:/data:ro -v "$PWD":/backup alpine \
	tar czf /backup/bridge-data-v1.tgz -C /data .

Keep the archive until users have completed a full checkout, session, and checkin on v2.

Write the configuration file

Create a new folder for v2. In it, save this file as bridge.yaml. It turns on the browser protocols that v1 offered and turns on Britive login.

server:
  listen: 443
  log_level: info
  tls:
    enabled: true
  datastore:
    host: postgres
    port: 5432
    user: bridge
    password: bridge
    name: bridge
    sslmode: disable        # matches the postgres service in the Compose file
  recording:
    output_dir: /data/recordings
  auth:
    types: [britive]
    britive:
      tenant: your-tenant   # for example acme

ssh:
  idle_timeout: 30m
  allow_insecure_host_key: true   # transition only. See the scripts step.
  native:
    enabled: false
  browser:
    enabled: true

telnet:
  idle_timeout: 30m
  browser:
    enabled: true

rdp:
  idle_timeout: 30m
  browser:
    enabled: true

vnc:
  idle_timeout: 30m
  browser:
    enabled: true

k8s_exec:
  idle_timeout: 30m
  browser:
    enabled: true

Set server.auth.britive.tenant to your tenant.

Keep Britive login on. v2 opens the Admin console and recording review only to a user who has logged in. If you set server.auth.types: [], users can still open sessions, but nobody can review recordings.

If v1 used your own certificate, copy the files into a certs folder next to bridge.yaml. Then add these lines under server.tls:

    cert_path: /etc/britive-bridge/certs/api-cert.pem
    key_path: /etc/britive-bridge/certs/api-key.pem

Write the Compose file

Save this file as docker-compose.yaml in the same folder. It is the published single-server Compose file with two changes: the broker variables are set, and native SSH is not published.

services:
  export:
    image: britive/bridge:v2.3.1
    restart: unless-stopped
    environment:
      BRIDGE_ROLE: export
    user: "102:103"
    network_mode: none
    read_only: true
    cap_drop: [ALL]
    security_opt: [no-new-privileges:true]
    mem_limit: "1g"
    cpus: "1"
    tmpfs:
      - /tmp:size=1g,mode=1777
    volumes:
      - recordings:/data/recordings

  postgres:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: bridge
      POSTGRES_PASSWORD: bridge
      POSTGRES_DB: bridge
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "bridge"]
      interval: 5s
      retries: 10

  bridge:
    image: britive/bridge:v2.3.1
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      BRIDGE_CONFIG: /etc/britive-bridge/config.yaml
      BRIDGE_ENCRYPTION_KEY_B64: "${BRIDGE_ENCRYPTION_KEY_B64:?set BRIDGE_ENCRYPTION_KEY_B64 in .env}"
      BRITIVE_BROKER_TENANT_SUBDOMAIN: "${BRITIVE_BROKER_TENANT_SUBDOMAIN}"
      BRITIVE_BROKER_AUTH_TOKEN: "${BRITIVE_BROKER_AUTH_TOKEN}"
    volumes:
      - ./bridge.yaml:/etc/britive-bridge/config.yaml:ro
      - recordings:/data/recordings
    ports:
      - "443:443"

volumes:
  pgdata:
  recordings:

If you copied your own certificate in the previous step, add this line under bridge.volumes:

      - ./certs:/etc/britive-bridge/certs:ro

Create the .env file

Generate the encryption key:

openssl rand -base64 32

Write the key and the two broker values from v1 into .env, next to the Compose file:

BRIDGE_ENCRYPTION_KEY_B64=<the generated key>
BRITIVE_BROKER_TENANT_SUBDOMAIN=<tenant subdomain>
BRITIVE_BROKER_AUTH_TOKEN=<broker pool token>

With the broker token set, Bridge fetches its license from your tenant and renews it. Without a license, Bridge runs only browser sessions and turns off live view, session control, and downloads. See Licensing.

Copy the recordings

Copy the recordings before the first v2 start. Bridge imports v1 recordings once, on its first start against an empty database.

Create the v2 volumes without starting any service:

docker compose up --no-start

Copy the recordings from the v1 volume and give them to the v2 user, 102:103. Replace bridge_bridge-data with your volume name:

docker compose run --rm --no-deps -v bridge_bridge-data:/v1:ro \
	--entrypoint sh bridge -c \
	'cp -a /v1/recordings/. /data/recordings/ && chown -R 102:103 /data/recordings'

Check the copy. The output lists date folders, such as 2026, and metadata.db:

docker compose run --rm --no-deps --entrypoint ls bridge -ln /data/recordings

Use the published v2 scripts

The v2 scripts are in britive/access-broker-examples. Each folder’s README lists the script parameters that the profile needs.

In the v2 scripts, the BRIDGE_URL parameter is a host name, such as bridge.example.com, not a URL.

The SSH and RDP scripts sign users in with a Bridge password. Add BRIDGE_AUTH_PASSWORD to those permissions.

The published SSH script does not send target_ssh_host_key. Keep ssh.allow_insecure_host_key: true while you use it unmodified. To turn verification on, add the field to the script’s payload and set the setting to false.

Edit the remaining scripts

For VNC, Telnet, and Kubernetes exec, edit your v1 script. Keep the helper path, /opt/britive-broker/scripts/bridge.sh.

1. Delete every --admin-token and --cluster-token option. The helper script rejects them as unknown options.
2. Delete every --api-url option and every line that sets BRIDGE_API_URL or BRIDGE_ADMIN_TOKEN. v2 configures the helper script for you.
3. Replace any curl call to the Bridge API with the helper script. v2 does not accept the v1 admin token.
4. Set the profile’s BRIDGE_URL parameter to the host name.
5. Return the launch link without the token:

URL="https://${BRIDGE_URL}/connect?transaction_id=${TRANSACTION_ID}"

The user logs in with Britive, and Bridge opens the session page for the checkout’s protocol. The other v1 checkout fields work as before. See the Payload reference.

Check the API

The health endpoint returns {"status":"ok"}:

curl -sk https://localhost/api/health

Open the Admin console

Check out the admin profile on your tenant and open the returned link. Log in with Britive. The session list opens, and the floating Admin button appears.

The admin checkout’s username must be the Britive identity the user logs in with. An admin checkout grants nothing to any other login.

Play a v1 recording

Open a v1 session in the session list and play its recording.

Run a new session

Check out a user profile, open the link, and connect. End the session. Confirm that the session list shows it with a recording.