Caution

This page documents the latest, unreleased version of Buildbot. For documentation for released versions, see https://docs.buildbot.net/current/.

2.5.17.1. Web Server

Buildbot contains a built-in web server. This server is configured with the www configuration key, which specifies a dictionary with the following keys:

port

The TCP port on which to serve requests. It might be an integer or any string accepted by serverFromString (ex: “tcp:8010:interface=127.0.0.1” to listen on another interface). Note that using twisted’s SSL endpoint is discouraged. Use a reverse proxy that offers proper SSL hardening instead (see Reverse Proxy Configuration). If this is None (the default), then the master will not implement a web server.

json_cache_seconds

The number of seconds into the future at which an HTTP API response should expire.

rest_minimum_version

The minimum supported REST API version. Any versions less than this value will not be available. This can be used to ensure that no clients are depending on API versions that will soon be removed from Buildbot.

plugins

This key gives a dictionary of additional UI plugins to load, along with configuration for those plugins. These plugins must be separately installed in the Python environment, e.g., pip install buildbot-waterfall-view. See UI plugins. For example:

c['www'] = {
    'plugins': {'waterfall_view': True}
}

default_page

Configure the default landing page of the web server, for example, to forward directly to another plugin. For example:

c['www']['default_page'] = 'console'

debug

If true, then debugging information will be output to the browser. This is best set to false (the default) on production systems, to avoid the possibility of information leakage.

allowed_origins

This gives a list of origins which are allowed to access the Buildbot API (including control via JSONRPC 2.0). It implements cross-origin request sharing (CORS), allowing pages at origins other than the Buildbot UI to use the API. Each origin is interpreted as filename match expression, with ? matching one character and * matching anything. Thus ['*'] will match all origins, and ['https://*.buildbot.net'] will match secure sites under buildbot.net. The Buildbot UI will operate correctly without this parameter; it is only useful for allowing access from other web applications.

auth

Authentication module to use for the web server. See Authentication plugins.

avatar_methods

List of methods that can be used to get avatar pictures to use for the web server. By default, Buildbot uses Gravatar to get images associated with each users, if you want to disable this you can just specify empty list:

c['www'] = {
    'avatar_methods': []
}

You could also use the GitHub user avatar if GitHub authentication is enabled:

c['www'] = {
    'avatar_methods': [util.AvatarGitHub()]
}

class AvatarGitHub(github_api_endpoint=None, token=None, debug=False, verify=True)

Parameters:

github_api_endpoint (string) – specify the github api endpoint if you work with GitHub Enterprise
token (string) – a GitHub API token to execute all requests to the API authenticated. It is strongly recommended to use a API token since it increases GitHub API rate limits significantly
client_id (string) – a GitHub OAuth client ID to use with client secret to execute all requests to the API authenticated in place of token
client_secret (string) – a GitHub OAuth client secret to use with client ID above
debug (boolean) – logs every requests and their response
verify (boolean) – disable ssl verification for the case you use temporary self signed certificates on a GitHub Enterprise installation

This class requires txrequests package to allow interaction with GitHub REST API.

For use of corporate pictures, you can use LdapUserInfo, which can also act as an avatar provider. See Authentication plugins.

logfileName

Filename used for HTTP access logs, relative to the master directory. If set to None or the empty string, the content of the logs will land in the main twisted.log log file. (Defaults to http.log)

logRotateLength

The amount of bytes after which the http.log file will be rotated. (Defaults to the same value as for the twisted.log file, set in buildbot.tac)

maxRotatedFiles

The amount of log files that will be kept when rotating (Defaults to the same value as for the twisted.log file, set in buildbot.tac)

versions

Custom component versions that you’d like to display on the About page. Buildbot will automatically prepend the versions of Python, twisted and Buildbot itself to the list.

versions should be a list of tuples. For example:

c['www'] = {
    # ...
    'versions': [
        ('master.cfg', '0.1'),
        ('OS', 'Ubuntu 14.04'),
    ]
}

The first element of a tuple stands for the name of the component, the second stands for the corresponding version.

custom_templates_dir

This directory will be parsed for custom angularJS templates to replace the one of the original website templates. You can use this to slightly customize buildbot look for your project, but to add any logic, you will need to create a full-blown plugin. If the directory string is relative, it will be joined to the master’s basedir. Buildbot uses the jade file format natively (which has been renamed to ‘pug’ in the nodejs ecosystem), but you can also use HTML format if you prefer.

Either *.jade files or *.html files can be used to override templates with the same name in the UI. On the regular nodejs UI build system, we use nodejs’s pug module to compile jade into html. For custom_templates, we use the pypugjs interpreter to parse the jade templates, before sending them to the UI. pip install pypugjs is required to use jade templates. You can also override plugin’s directives, but they have to be in another directory, corresponding to the plugin’s name in its package.json. For example:

# replace the template whose source is in:
# www/base/src/app/builders/build/build.tpl.jade
build.jade  # here we use a jade (aka pug) file

# replace the template whose source is in
# www/console_view/src/module/view/builders-header/console.tpl.jade
console_view/console.html  # here we use html format

Known differences between nodejs’s pug and pyjade:

quotes in attributes are not quoted (https://github.com/syrusakbary/pyjade/issues/132). This means you should use double quotes for attributes, e.g.: tr(ng-repeat="br in buildrequests | orderBy:'-submitted_at'")

pypugjs may have some differences but it is a maintained fork of pyjade. https://github.com/kakulukia/pypugjs

change_hook_dialects

See Change Hooks.

cookie_expiration_time

This allows to define the timeout of the session cookie. Should be a datetime.timedelta. Default is one week.
import datetime
c['www'] = {
    # ...
    'cookie_expiration_time': datetime.timedelta(weeks=2)
}

ui_default_config

Settings in the settings page are stored per browser. This configuration parameter allows to override the default settings for all your users. If a user already has changed a value from the default, this will have no effect to them. The settings page in the UI will tell you what to insert in your master.cfg to reproduce the configuration you have in your own browser. For example:
c['www']['ui_default_config'] = {
    'Builders.buildFetchLimit': 500,
    'Workers.showWorkerBuilders': True,
}

ws_ping_interval

Send websocket pings every ws_ping_interval seconds. This is useful to avoid websocket timeouts when using reverse proxies or CDNs. If the value is 0 (the default), pings are disabled.

theme

Allows configuring certain properties of the web frontend, such as colors. The configuration value is a dictionary. The keys correspond to certain CSS variable names that are used throughout web frontend and made configurable. The values correspond to CSS values of these variables.

The keys and values are not sanitized, so using data derived from user-supplied information is a security risk.

The default is the following:
c["www"]["theme"] = {
    "bb-sidebar-background-color": "#30426a",
    "bb-sidebar-header-background-color": "#273759",
    "bb-sidebar-header-text-color": "#fff",
    "bb-sidebar-title-text-color": "#627cb7",
    "bb-sidebar-footer-background-color": "#273759",
    "bb-sidebar-button-text-color": "#b2bfdc",
    "bb-sidebar-button-hover-background-color": "#1b263d",
    "bb-sidebar-button-hover-text-color": "#fff",
    "bb-sidebar-button-current-background-color": "#273759",
    "bb-sidebar-button-current-text-color": "#b2bfdc",
    "bb-sidebar-stripe-hover-color": "#e99d1a",
    "bb-sidebar-stripe-current-color": "#8c5e10",
}

Note

The buildbotURL configuration value gives the base URL that all masters will use to generate links. The www configuration gives the settings for the webserver. In simple cases, the buildbotURL contains the hostname and port of the master, e.g., http://master.example.com:8010/. In more complex cases, with multiple masters, web proxies, or load balancers, the correspondence may be less obvious.