Skip to content

Server Configuration


The BrainFrame server uses a docker-compose.yml file to configure many aspects of its runtime behavior. Some options may be changed by setting environment variables in a .env file, placed in the same directory as the docker-compose.yml file.

Any options not exposed here may be overridden by creating a docker-compose.override.yml file in the same directory. Configuration written here will be applied over the original docker-compose.yml.

Port Configuration

BrainFrame makes three ports available to the host environment by default, the API and documentation on port 80, the Postgres database on port 5432, and the StreamGateway server on port 8004. If these ports conflict with other software running on the host machine, they can be changed by setting the SERVER_PORT, DATABASE_PORT, and STREAM_GATEWAY_PORT variables in the .env file.

BrainFrame may also proxy video streams to ports in the range 10000-20000. At this time, there is no way to reconfigure these ports.


Authorization Configuration

By default, BrainFrame does not authorize clients and all clients have admin permissions. If your server is being deployed in a network where access control is desirable, authorization can be turned on using the AUTHORIZE_CLIENTS variable in the .env file.



The admin user is given a default password of "admin". This should be changed to a secure and unique password for public deployments.

Currently, the admin user's password may only be changed through the REST API. The following is an example curl command for doing this. Replace [hostname] with the hostname of the BrainFrame server and [new password] with the desired password.

curl 'http://[hostname]/api/users' \                      
    --user 'admin:admin' \
    --request POST \
    --header 'Content-Type: application/json' \
    --data '{
              "id": 1,
              "username": "admin",
              "password": "[new password]",
              "role": "admin"

User Configuration

BrainFrame is designed to run using the account of the current non-root user. By default, 1000 is used for both the user ID and group ID, which matches the default on most Linux systems. These IDs may be adjusted using the UID and GID variables in the .env file.


To check the IDs of the currently logged in user, run id -u for the UID and id -g for the GID.

Journal Pruning

BrainFrame records analytics results to a Postgres database. Over a long period of time, this can result in a lot of data. To avoid unbounded storage use, BrainFrame prunes journal entries over time and deletes journal entries that are past a certain age.

Journal pruning behavior is controlled by the "pruning age" and "pruning fraction" variables. The pruning age controls how old a journal entry must be before it becomes a candidate for pruning. This value also controls at what interval pruning is run. The pruning fraction variable controls what portion of journal entries are pruned each time pruning is run. The pruning fraction variable is a value between 0 and 1, where 0 results in no pruning, and 1 results in the deletion of all journaling information past the pruning age. These variables may be configured by setting the PRUNING_AGE (specified as a duration) and PRUNING_FRACTION variables in the .env file.

# Start pruning journal entries after 1 hour, and run pruning every hour
# Prune 5% of all journal entries that are past the pruning age every run

All journaling information is deleted after it reaches the journal max age. This value may be configured by setting the JOURNAL_MAX_AGE variable (specified as a duration) in the .env file.

# Keep journaling information for 60 days

Duration Format

Settings that specify a duration are in the format XdYhZm, where X is the number of days, Y is the number of hours, and Z is the number of minutes.

Stateless Operation

By default, BrainFrame saves configuration and journaling information to a Postgres database. That data will survive between restarts of BrainFrame. If this behavior is not desirable, BrainFrame may be configured to use an in-memory database that is discarded after each restart by setting the DBMS variable in the .env file.


When using an in-memory database, be sure to set the JOURNAL_MAX_AGE value to a low number to avoid excessive memory usage.

Algorithm Configuration

At the moment the only control over algorithms is for OpenVINO devices. It is possible to change the whitelisted devices and their priority with the OPENVINO_DEVICES_PRIORITY.

# Block any device except for CPU

# Load onto both CPU and HDDL, giving priority to CPU

# Load onto both CPU and HDDL, giving priority to HDDL