Skip to content

Getting Started

Introduction

The BrainFrame ecosystem includes a server for the video processing and a client to view the live results and configure the server.

The server requires a Linux machine, and the client can run on either Ubuntu or Windows. It is possible to install and run BrainFrame on Linux variants other than Ubuntu. However, the continuous integration of releases is tested only on Ubuntu, and only ==x86 architectures== are available in the general public releases.

Prerequisites: Python and Docker

First, let's install pip, which will be used install 'brainframe-cli' in the next section:

sudo apt update && sudo apt upgrade
sudo apt install -y python3-pip
pip3 install --upgrade pip

BrainFrame Server requires Docker. Ensure Docker is installed on your system. If it is not, you can install it using the following commands

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

After installation, add your user to the Docker group to manage Docker as a non-root user:

sudo usermod -aG docker $USER
newgrp docker

BrainFrame CLI

For this guide, we will use the brainframe-cli (Command Line Interface) to download and install BrainFrame. This tool requires Ubuntu.

For Ubuntu 20.04 and 22.04, use pip to install the brainframe-cli:

sudo -H pip3 install --upgrade brainframe-cli

If you are using Ubuntu 24.04 with Python 3.12, virtual environment is required before the 'brainframe-cli' installation:

sudo apt install -y python3-venv
python3 -m venv my_venv
source my_venv/bin/activate
pip3 install --upgrade brainframe-cli

Starting the BrainFrame Server

With the tool installed, now you can use the brainframe command. You can navigate the available commands from BrainFrame CLI by running:

brainframe --help

Now, install BrainFrame by running the below command and following the directions:

sudo brainframe install

Info

If you are in mainland China and downloading the BrainFrame Docker images is taking a long time, consider using a Docker mirror by following these instructions.

Once BrainFrame is downloaded, the BrainFrame CLI will ask you if you want to start BrainFrame server now or not. You can either start BrainFrame server now, or with the following command later:

sudo brainframe compose up -d

Then to view logs live:

sudo brainframe compose logs -f

Info

If you said Yes to adding your user to the brainframe group during the installation, then rebooting your computer will allow you to use brainframe commands without needing sudo.

Install a specified BrainFrame Release

By default, 'brainframe install' will install the latest version. To update to a specified BrainFrame release, use the following command:

sudo -E brainframe update --version v{#.#.#.#}

If you are an early access partner, set up the environment variable for your staging access before running the 'brainframe update' command:

export BRAINFRAME_STAGING_USERNAME={username}
export BRAINFRAME_STAGING_PASSWORD={password}
BRAINFRAME_STAGING=yes sudo -E brainframe update --version v{#.#.#.#}

BrainFrame currently offers stable and main releases. For production deployment, the latest stable release is recommended.

  • Stable release: v0.29.#.#
  • Main release: v0.30.#.#

Install BrainFrame Client

You can download our client app for Windows or Linux from here.

On Windows, run the BrainFrameClient.exe.

On the first run on Linux, run the installation script. Then, run the client.

bash install.sh
bash brainframe_client.sh

Getting a License

The client will now request a license be uploaded to the server, like such:

To get a license:

  1. Go to the website.
  2. Click the "Sign In" button located near the top of the page.
  3. Either sign in with your existing account or click "Sign Up" to create a new account.
  4. On the Account Page, under the "License Key" section, click "Create a New Key". Then, click "Download Key" once the option appears.

Now on the client, select "Configure" and then "License Config". Drag in the downloaded license_file into the window, then select "Update License". It should complete looking like this:

Close the license config and the server config windows, and the client will open!

Next Steps

Now with the BrainFrame server and client installed, you can go on to use the ecosystem to your full advantage.