The binderhub application


class**kwargs: Any)#

An Application for starting a builder.

about_message c.BinderHub.about_message = Unicode('')#

Additional message to display on the about page.

Will be directly inserted into the about page’s source so you can use raw HTML.

static add_url_prefix(prefix, handlers)#

add a url prefix to handlers

appendix c.BinderHub.appendix = Unicode('')#

DEPRECATED: Use c.BuildExecutor.appendix

Appendix to pass to repo2docker

A multi-line string of Docker directives to run. Since the build context cannot be affected, ADD will typically not be useful.

This should be a Python string template. It will be formatted with at least the following names available:

  • binder_url: the shareable URL for the current image (e.g. for sharing links to the current Binder)

  • repo_url: the repository URL used to build the image

auth_enabled c.BinderHub.auth_enabled = Bool(False)#

If JupyterHub authentication enabled, require user to login (don’t create temporary users during launch) and start the new server for the logged in user.

badge_base_url c.BinderHub.badge_base_url = Union()#

Base URL to use when generating launch badges. Can also be a function that is passed the current handler and returns the badge base URL, or “” for the default.

For example, you could get the badge_base_url from a custom HTTP header, the Referer header, or from a request parameter

ban_networks c.BinderHub.ban_networks = Dict()#

Dict of networks from which requests should be rejected with 403

Keys are CIDR notation (e.g. ‘’), values are a label used in log / error messages. CIDR strings will be parsed with ipaddress.ip_network().

ban_networks_min_prefix_len Int(1)#

The shortest prefix in ban_networks

banner_message c.BinderHub.banner_message = Unicode('')#

Message to display in a banner on all pages.

The value will be inserted “as is” into a HTML <div> element with grey background, located at the top of the BinderHub pages. Raw HTML is supported.

base_url c.BinderHub.base_url = Unicode('/')#

The base URL of the entire application

build_class c.BinderHub.build_class = Type(<class ''>)#

The class used to build repo2docker images.

Must inherit from

build_cleaner_class c.BinderHub.build_cleaner_class = Type(<class ''>)#

The class used to cleanup builders.

build_cleanup_interval c.BinderHub.build_cleanup_interval = Int(60)#

Interval (in seconds) for how often stopped build pods will be deleted.

build_docker_config c.BinderHub.build_docker_config = Dict()#

A dict which will be merged into the .docker/config.json of the build container (repo2docker) Here, you could for example pass proxy settings as described here:

Note: if you provide your own push_secret, this values wont have an effect, as the push_secrets will overwrite .docker/config.json In this case, make sure that you include your config in your push_secret

WARNING: The value of this parameter is managed by the binderHub Helm Chart. It is not managed by the BinderHub application itself. If you are running BinderHub in another way this parameter has no effect.

build_docker_host c.BinderHub.build_docker_host = Unicode('/var/run/docker.sock')#

DEPRECATED: Use c.KubernetesBuildExecutor.docker_host

The docker URL repo2docker should use to build the images.

Currently, only paths are supported, and they are expected to be available on all the hosts.

build_image c.BinderHub.build_image = Unicode('')#

DEPRECATED: Use c.KubernetesBuildExecutor.build_image

The repo2docker image to be used for doing builds

build_max_age c.BinderHub.build_max_age = Int(14400)#

Maximum age of builds

Builds that are still running longer than this will be killed.

build_memory_limit c.BinderHub.build_memory_limit = ByteSpecification(0)#

DEPRECATED: Use c.BuildExecutor.memory_limit

Max amount of memory allocated for each image build process.

0 sets no limit.

This is applied to the docker build itself via repo2docker, though it is also applied to our pod that submits the build, even though that pod will rarely consume much memory. Still, it makes it easier to see the resource limits in place via kubernetes.

build_memory_request c.BinderHub.build_memory_request = ByteSpecification(0)#

DEPRECATED: Use c.KubernetesBuildExecutor.memory_request

Amount of memory to request when scheduling a build

0 reserves no memory.

This is used as the request for the pod that is spawned to do the building, even though the pod itself will not be using that much memory since the docker building is happening outside the pod. However, it makes kubernetes aware of the resources being used, and lets it schedule more intelligently.

build_namespace c.BinderHub.build_namespace = Unicode('')#

DEPRECATED: Use c.KubernetesBuildExecutor.namespace

Kubernetes namespace to spawn build pods in.

Note that the push_secret must refer to a secret in this namespace.

build_node_selector c.BinderHub.build_node_selector = Dict()#

DEPRECATED: Use c.KubernetesBuildExecutor.node_selector

Select the node where build pod runs on.

build_token_check_origin c.BinderHub.build_token_check_origin = Bool(True)#

Whether to validate build token origin.

False disables the origin check.

build_token_expires_seconds c.BinderHub.build_token_expires_seconds = Int(300)#

Expiry (in seconds) of build tokens

These are generally only used to authenticate a single request from a page, so should be short-lived.

build_token_secret c.BinderHub.build_token_secret = Union()#

Secret used to sign build tokens

Lightweight validation of same-origin requests

builder_required c.BinderHub.builder_required = Bool(True)#

If binderhub should try to continue to run without a working build infrastructure.

Build infrastructure is kubernetes cluster + docker. This is useful for pure HTML/CSS/JS local development.

concurrent_build_limit c.BinderHub.concurrent_build_limit = Int(32)#

The number of concurrent builds to allow.

config_file c.BinderHub.config_file = Unicode('')#

Config file to load.

If a relative path is provided, it is taken relative to current directory

cors_allow_origin c.BinderHub.cors_allow_origin = Unicode('')#

Origins that can access the BinderHub API.

Sets the Access-Control-Allow-Origin header in the spawned notebooks. Set to ‘*’ to allow any origin to access spawned notebook servers.

See also BinderSpawner.cors_allow_origin in the binderhub spawner mixin for setting this property on the spawned notebooks.

debug c.BinderHub.debug = Bool(False)#

Turn on debugging.

enable_api_only_mode c.BinderHub.enable_api_only_mode = Bool(False)#

When enabled, BinderHub will operate in an API only mode, without a UI, and with the only registered endpoints being:

  • /metrics

  • /versions

  • /build/([^/]+)/(.+)

  • /health

  • /_config

  • /* -> shows a 404 page

executor_threads c.BinderHub.executor_threads = Int(5)#

The number of threads to use for blocking calls

Should generally be a small number because we don’t care about high concurrency here, just not blocking the webserver. This executor is not used for long-running tasks (e.g. builds).

Extra bits of JavaScript that should be loaded in footer of each page.

Only the values are set up as scripts. Keys are used only for sorting.

Omit the <script> tag. This should be primarily used for analytics code.

extra_static_path c.BinderHub.extra_static_path = Unicode('')#

Path to search for extra static files.

extra_static_url_prefix c.BinderHub.extra_static_url_prefix = Unicode('/extra_static/')#

Url prefix to serve extra static files.

google_analytics_code c.BinderHub.google_analytics_code = Unicode(None)#

The Google Analytics code to use on the main page.

Note that we’ll respect Do Not Track settings, despite the fact that GA does not. We will not load the GA scripts on browsers with DNT enabled.

google_analytics_domain c.BinderHub.google_analytics_domain = Unicode('auto')#

The Google Analytics domain to use on the main page.

By default this is set to ‘auto’, which sets it up for current domain and all subdomains. This can be set to a more restrictive domain here for better privacy

health_handler_class c.BinderHub.health_handler_class = Type(<class ''>)#

The Tornado /health handler class

hub_api_token c.BinderHub.hub_api_token = Unicode('')#

API token for talking to the JupyterHub API

hub_url c.BinderHub.hub_url = Unicode('')#

The base URL of the JupyterHub instance where users will run.


hub_url_local c.BinderHub.hub_url_local = Unicode('')#

The base URL of the JupyterHub instance for local/internal traffic

If local/internal network connections from the BinderHub process should access JupyterHub using a different URL than public/external traffic set this, default is hub_url

image_prefix c.BinderHub.image_prefix = Unicode('')#

Prefix for all built docker images.

If you are pushing to, this would start with:<your-project-name>/

Set according to whatever registry you are pushing to.

Defaults to “”, which is probably not what you want :)

initialize(*args, **kwargs)#

Load configuration settings.

launch_quota_class c.BinderHub.launch_quota_class = Type(<class 'binderhub.quota.KubernetesLaunchQuota'>)#

The class used to check quotas for launched servers.

Must inherit from binderhub.quota.LaunchQuota

log_datefmt c.BinderHub.log_datefmt = Unicode('%Y-%m-%d %H:%M:%S')#

The date format used by logging formatters for %(asctime)s

log_format c.BinderHub.log_format = Unicode('[%(name)s]%(highlevel)s %(message)s')#

The Logging format template

log_level c.BinderHub.log_level = Enum(30)#

Set the log level by value or name.

log_tail_lines c.BinderHub.log_tail_lines = Int(100)#

DEPRECATED: Use c.KubernetesBuildExecutor.log_tail_lines

Limit number of log lines to show when connecting to an already running build.

logging_config c.BinderHub.logging_config = Dict()#

Configure additional log handlers.

The default stderr logs handler is configured by the log_level, log_datefmt and log_format settings.

This configuration can be used to configure additional handlers (e.g. to output the log to a file) or for finer control over the default handlers.

If provided this should be a logging configuration dictionary, for more information see:

This dictionary is merged with the base logging configuration which defines the following:

  • A logging formatter intended for interactive use called console.

  • A logging handler that writes to stderr called console which uses the formatter console.

  • A logger with the name of this application set to DEBUG level.

This example adds a new handler that writes to a file:

c.Application.logging_config = {
    'handlers': {
        'file': {
            'class': 'logging.FileHandler',
            'level': 'DEBUG',
            'filename': '<path/to/file>',
    'loggers': {
        '<application-name>': {
            'level': 'DEBUG',
            # NOTE: if you don't list the default "console"
            # handler here then it will be disabled
            'handlers': ['console', 'file'],
normalized_origin c.BinderHub.normalized_origin = Unicode('')#

Origin to use when emitting events. Defaults to hostname of request when empty

per_repo_quota c.BinderHub.per_repo_quota = Int(0)#

Maximum number of concurrent users running from a given repo.

Limits the amount of Binder that can be consumed by a single repo.

0 (default) means no quotas.

per_repo_quota_higher c.BinderHub.per_repo_quota_higher = Int(0)#

Maximum number of concurrent users running from a higher-quota repo.

Limits the amount of Binder that can be consumed by a single repo. This quota is a second limit for repos with special status. See the high_quota_specs parameter of RepoProvider classes for usage.

0 (default) means no quotas.

pod_quota c.BinderHub.pod_quota = Int(None)#

DEPRECATED: Use c.LaunchQuota.total_quota

The number of concurrent pods this hub has been designed to support.

This quota is used as an indication for how much above or below the design capacity a hub is running.

Attempts to launch new pods once the quota has been reached will fail.

The default corresponds to no quota, 0 means the hub can’t accept pods (maybe because it is in maintenance mode), and any positive integer sets the quota.

port c.BinderHub.port = Int(8585)#

Port for the builder to listen on.

push_secret c.BinderHub.push_secret = Unicode('binder-build-docker-config')#

DEPRECATED: Use c.BuildExecutor.push_secret

A kubernetes secret object that provides credentials for pushing built images.

registry_class c.BinderHub.registry_class = Type(<class 'binderhub.registry.DockerRegistry'>)#

The class used to Query a Docker registry.

Must inherit from binderhub.registry.DockerRegistry

repo_providers c.BinderHub.repo_providers = Dict()#

List of Repo Providers to register and try

show_config c.BinderHub.show_config = Bool(False)#

Instead of starting the Application, dump configuration to stdout

show_config_json c.BinderHub.show_config_json = Bool(False)#

Instead of starting the Application, dump configuration to stdout (as JSON)


Start the app mainloop.

Override in subclasses.

sticky_builds c.BinderHub.sticky_builds = Bool(False)#

DEPRECATED: Use c.KubernetesBuildExecutor.sticky_builds

Attempt to assign builds for the same repository to the same node.

In order to speed up re-builds of a repository all its builds will be assigned to the same node in the cluster.

Note: This feature only works if you also enable docker-in-docker support.

template_path c.BinderHub.template_path = Unicode('')#

Path to search for custom jinja templates, before using the default templates.

template_variables c.BinderHub.template_variables = Dict()#

Extra variables to supply to jinja templates when rendering.

tornado_settings c.BinderHub.tornado_settings = Dict()#

additional settings to pass through to tornado.

can include things like additional headers, etc.

use_registry c.BinderHub.use_registry = Bool(True)#

Set to true to push images to a registry & check for images in registry.

Set to false to use only local docker images. Useful when running in a single node.

async watch_builders()#

Watch builders, run a cleanup function every build_cleanup_interval