Setting Up a Bridge¶

This guide walks through registering a Bridge in the Zaita web portal and deploying it in your environment. For an overview of what a Bridge is and how it works, see Bridges — Introduction.

Prerequisites¶

Before you begin, ensure the following:

You are signed in to the Zaita web portal with the Deployment Administrator or Super Administrator role.
You have determined where the Bridge will be deployed and which deployment method you will use.
The deployment host has outbound HTTPS access (port 443) to the Zaita SaaS endpoint for your region.
The deployment host has network access to any target systems the Bridge will need to reach for certificate deployment or discovery.

Step 1 — Register the Bridge in the Web Portal¶

Before deploying the Bridge, you must register it in the platform. Registration generates the initial trust token used to establish the Bridge's identity.

Navigate to Admin → Bridges in the web portal.
Select Create Bridge.
Configure the Bridge:
- Name — a descriptive name identifying this Bridge (for example, Production Network — Sydney).
- Description — optional notes on this Bridge's role or location.
- Deployment Method — select Standalone Binary or Docker Container to match how you will run the Bridge on the target host.
- Instance Count — the number of instances to create (1–10). Each instance is independently deployed and receives its own registration token. For production environments, set this to 2 or more for high availability.
Select Create. The portal will display a registration token for each instance.

Important: Copy each registration token before navigating away. Tokens are shown immediately after creation. If a token is lost before the instance has registered, it can be regenerated from the Bridge detail page — locate the pending instance and select Regenerate Token. Once an instance has completed registration its token cannot be regenerated.

Additional instances can be added to an existing Bridge at any time from the Bridge detail page. See Managing Bridges for details.

Step 2 — Choose a Deployment Method¶

Select the deployment method that matches what you configured in Step 1:

Method	Best For
Standalone Binary	Any supported host — Windows (installs as a service via the `.exe` installer), Linux (installs as a SystemD service via the `.deb` / `.rpm` package), or bare binary for hosts where a system installation is not required
Docker Container	Container environments; requires a persistent volume for state storage

Step 3 — Deploy the Bridge¶

Option A: Windows Installer¶

Download the Windows installer (.exe) from the Zaita web portal under Admin → Bridges → Download.

Run the installer on the target Windows server. The installer will:

Install the Bridge binary to the configured installation directory.
Register and start a Windows service (ZaitaBridge).
Prompt for the registration token and regional API URL during setup.

Once installed, the Bridge service starts automatically and completes the initial trust handshake with the SaaS. The service is configured to start automatically on system boot.

To verify installation, open Services and confirm ZaitaBridge is running, or check the Bridge status in the web portal under Admin → Bridges.

Option B: Linux Package (.deb / .rpm)¶

Download the appropriate package for your distribution from the Zaita web portal under Admin → Bridges → Download.

Debian / Ubuntu:

sudo dpkg -i zaita-bridge.deb

RHEL / CentOS / Fedora:

sudo rpm -i zaita-bridge.rpm

After installation, configure the registration token and API URL:

sudo zaita-bridge configure \
  --token <your-registration-token> \
  --api-url https://au.zaita.com

Replace https://au.zaita.com with the endpoint for your account's region. See Signing In for regional URLs.

Enable and start the SystemD service:

sudo systemctl enable zaita-bridge
sudo systemctl start zaita-bridge

Option C: Standalone Binary¶

Download the Bridge binary for your platform from the Zaita web portal under Admin → Bridges → Download.

Place the binary in a directory with restricted access. The Bridge will create its trust token and key files in the same directory — ensure only the Bridge process user has read/write access to this location.

Run the Bridge, passing the registration token and API URL:

./zaita-bridge \
  --token <your-registration-token> \
  --api-url https://au.zaita.com

Option D: Docker Container¶

Pull the Bridge image from the Zaita container registry:

docker pull registry.zaita.com/bridge:latest

Run the container, passing the registration token as an environment variable and mounting a persistent volume for state storage:

docker run -d \
  --name zaita-bridge \
  --restart unless-stopped \
  -e ZAITA_REGISTRATION_TOKEN=<your-registration-token> \
  -e ZAITA_API_URL=https://au.zaita.com \
  -v zaita-bridge-data:/app/data \
  registry.zaita.com/bridge:latest

The Bridge stores its trust token and key pair in the mounted volume. This volume must persist across container restarts — without it, the Bridge will lose its trust relationship and require re-registration.

Note: Docker-based Bridges cannot be updated via the SaaS web portal. Updates require pulling a new image and restarting the container. See Managing Bridges for details.

Step 4 — Verify the Connection¶

Once the Bridge starts, it uses the registration token to complete the initial trust handshake with the SaaS control plane. After a successful handshake, the token is replaced with a rotating session token managed automatically by the Bridge.

To confirm the Bridge is connected:

Navigate to Admin → Bridges in the web portal.
Locate your Bridge and confirm the status shows Connected.
The Last Seen timestamp should update within a few minutes of deployment.

If the Bridge does not appear as connected within 5 minutes, see the Troubleshooting section below.

TLS Certificate¶

During the initial trust handshake, the Bridge automatically requests a TLS certificate from the Zaita platform. This certificate is used to secure Courier connections on port 443. No manual certificate configuration is required. The Bridge manages all subsequent renewals automatically. See Managing Bridges — TLS Certificates for more information.

Configuring Couriers to Use a Bridge¶

To route Courier traffic through a Bridge rather than directly to the SaaS, update the Courier's YAML configuration to point to the Bridge's address:

api:
  base_url: https://<bridge-host-or-ip>
  version: v1
  verify_tls: true

The Bridge does not need to be internet-accessible — it only needs to be reachable by Couriers within your internal network. See Couriers — Introduction for full configuration details.

Troubleshooting¶

Issue	Resolution
Bridge shows Disconnected in portal	Verify outbound HTTPS access to the Zaita SaaS endpoint. Confirm the registration token was entered correctly and has not been used previously.
Bridge shows Connected but jobs are not executing	Confirm the Bridge has network access to the relevant target systems. Check the Bridge logs for errors.
Trust token invalid error	The token has either expired or been used. Delete the Bridge in the portal, create a new one, and re-deploy with the new token.
Courier cannot reach the Bridge	Verify the Courier's `base_url` points to the Bridge's address. Confirm port 443 is accessible between the Courier host and the Bridge host.
Registration token lost	If the instance has not yet registered, open the Bridge detail page, locate the pending instance, and select Regenerate Token. If the instance has already registered, the token cannot be recovered — delete the instance and add a new one.
Linux service not starting	Check `journalctl -u zaita-bridge` for errors. Verify the configuration file contains a valid token and API URL.