Deploy Birch Probe

The Birch Probe communicates locally with your routers and the Birch cloud infrastructure to keep in sync with the router and make changes. You can run the Birch Probe on Linux, Mac or Windows using Docker Desktop or you can request an .ova for a virtualized environment.

Network Prerequisites

• The Birch Probe must be able to access your routing system via the local area network. If there is a firewall between the Birch Probe and the routing system, verify the necessary TCP ports are open.

• The Birch Probe must be able to access the internet to provide updates to the cloud infrastructure. Specific endpoints can be provided upon request.

Installing Docker Desktop

The installation process for Docker is different for each of the supported platforms. Please follow the steps provided by Docker for the host machine you will be deploying on.

• Linux

• Windows

• Mac

• Cloud

Start the Birch Probe container

Once Docker is available on your system, you need to connect to the Whitebark repository and download the Birch Probe container. The steps may be slightly different depending on your platform. The steps below are presented for Linux based distributions, but will be similar for other hosts as well.

This guide is based on a Linux host for the Birch Probe and some commands and arguments may look different if using a different host Operating System. Specifically the -v /var/data/birch_probe:/data argument in the docker run command binds a folder on your desktop with the Birch Probe container. The File Sharing process is specific to the host OS, therefore it's recommended to refer to Docker Desktop for Mac or Docker Desktop for Windows as needed.

1. Setup a data directory for persistent data from the Probe

The Birch Probe will store organization and id information persistently to your host to ensure it connects to the same organization if it reboots, as well as store log files locally for debugging. As such, a local directory is required. You can set this to any directory on your host, but the recommended directory is /var/data/birch_probe.

The Docker engine will read/write access to this directory. You can restrict this as much as you'd like, so long as Docker is able to continue to read/write from any file in this directory, there will be no impact. The provided example provides unrestricted access, which may or may not be appropriate for your environment.

sudo mkdir /var/data/birch_probe
sudo chmod 777 /var/data/birch_probe

2. Connect to the Whitebark repository

Use the Docker CLI to log into the Whitebark repository for access to the Birch Probe container.

docker login registry.gitlab.com -u probe -p X-nvregTQ4QkTez1p1wT

3. Start the Birch Probe Container

To start up the Birch Probe Container, you will need your Organization ID, which is available to Admin users in the Birch Settings.

Organization ID

Run the docker run command to download and start the Birch Probe container

docker run -d -e ORG_ID=d3e4e035-99cb-44fe-98e3-3315ee511478 -e AMPLIFY_ENV=production --name birch_probe --restart unless-stopped -p 4396:4396 -v /var/data/birch_probe:/data registry.gitlab.com/whitebark/birch/probe

If needed, the Birch Probe will download from the repository and start.

Beta Access

If you have been given access to the Beta program, you will need to modify the Docker command slightly. If needed in any of the Docker commands, adjust these two settings:

AMPLIFY_ENV=staging registry.gitlab.com/whitebark/birch/probe:beta

Your Organization ID for your Beta account will be different than your Organization ID for your primary account. Be sure to launch double check your ID when launching a Beta Probe.

docker run -d -e ORG_ID=d3e4e035-99cb-44fe-98e3-3315ee511478 -e AMPLIFY_ENV=staging --name birch_probe --restart unless-stopped -p 4396:4396 -v /var/data/birch_probe:/data registry.gitlab.com/whitebark/birch/probe:beta

Update the Probe

To update your Birch Probe to the latest version, run the following set of Docker commands

docker rm -f birch_probe
docker pull registry.gitlab.com/whitebark/birch/probe
docker run -d -e ORG_ID=d3e4e035-99cb-44fe-98e3-3315ee511478 -e AMPLIFY_ENV=production --name birch_probe --restart unless-stopped -p 4396:4396 -v /var/data/birch_probe:/data registry.gitlab.com/whitebark/birch/probe