Quick start guide


A Python version >=3.5 is required to install livebridge, since it is based and makes heavy use of Asyncio, an event loop introduced by Python3.

pip3 install livebridge

A livebridge command will be available afterwards.

$ livebridge
usage: livebridge [-h] --control CONTROL
livebridge: error: the following arguments are required: --control


It is recommended, to install Livebridge in a dedicated Virtualenv Python environment!


The specific bridges will be specified in an extra .yaml control file or in a database table!

Some global settings are defined in livebridge/config.py. These values can be set through environment variables. Following variables for configuration are available:

  • LB_CONTROLFILE - path to control file, overrides –control commandline argument.
  • LB_LOGLEVEL - Python logging level, INFO is default, can be DEBUG, INFO, WARNING, ERROR or CRITICAL
  • LB_LOGFILE - path to write a logfile, optional
  • LB_POLL_INTERVAL - interval in seconds for polling an API for new posts when using a polling-source, defaults to 60 seconds. Please be attentitive how often you are polling your source. Liveticker have other constraints like RSS Feeds!
  • LB_POLL_CONTROL_INTERVAL - interval in seconds for polling for control data changes, defaults to 60 seconds. This does not apply to local control files. If not configured otherwise, a restart is neccessary after changes to local control files.
  • LB_CONTROLFILE_WATCH - setting to true will force checks on local control files for changed control data.
  • LB_MAX_RETRIES - number of maximal retries for redistributing a failed item, defaults to 10.
  • LB_RETRY_MULTIPLIER - delay multiplier for retrying a failed distribution, defaults to 5 seconds. Retry delay is calclulated by multiplicating LB_RETRY_MULTIPLIER with the number of the last retry.

To use MongoDB or any SQL database supported by SQLALchemy as storage backend, you have to specify the following two environment variables:

  • LB_DB_DSN - dsn database url for connecting with a database, see docs for SQLAlchemy engines or MongoDB connection strings for details. To disable storage, set this env-var to dummy://.
  • LB_DB_TABLE - name of the database table which stores distribution related data, defaults to livebridge_dev.
  • LB_DB_CONTROL_TABLE - name of the database table, which stores control data in JSON format, overrides –control.
Be sure the database already exists and the database user from the dsn-url string has sufficient rights.


For simple, straight forward distribution, storage can be disabled by setting LB_DSN_DB=dummy://. Updates and deletes of distributed posts will therefore be not applied.

Since livebridge also supports AWS DynamoDB as storage backend, following Amazon AWS related config variables are available:

  • LB_AWS_ACCESS_KEY - AWS access key
  • LB_AWS_SECRET_KEY - AWS secret access key
  • LB_AWS_REGION - defaults to eu-central-1
  • LB_DYNAMO_ENDPOINT - Endpoint url for DynamoDB. Can be empty, except when using a local DynamoDB.
  • LB_DYNAMO_TABLE - Tablename, defaults to livebridge-posts.
  • LB_DYNAMO_CONTROL_TABLE - name of the DynamoDB table, which stores control data in JSON format, overrides –control.
  • LB_SQS_S3_QUEUE - SQS-QueueUrl for listening for control file changes on S3.
The DynamoDB tables will be automatically created, if defined and they’re not existing. Sufficient AWS IAM rights are required.

For using the Web-API following settings have to be set:

  • LB_WEB_HOST - the host the server is listening on. or for example.
  • LB_WEB_PORT - the port the server is listening on, 8080 for example.
  • LB_WEB_USER - Username of the API user. Only a single user supported at the moment!
  • LB_WEB_PWD - Password of the API user.

See Web-API for more details.


Livebridge uses pytest and asynctest for testing.

Run tests:

py.test -v tests/

Run tests with test coverage:

py.test -v --cov=livebridge --cov-report=html tests/

pytest-cov has to be installed. In the example above, a html summary of the test coverage is saved in ./htmlcov/.