Hosting Scopes

This page is for teams looking to self-host a Bit Scope.
This guide assumes familiarity with Docker.

When building your on-site hosting for Bit scopes, we recommend using a solution like Docker. This guide will walk you through the various aspects of managing multiple scopes, their storage, and how to ensure backup and monitoring.

Docker images

In this guide you will use the base images provided by Bit as a platform.

  • bit-cli container is an image generated with each new release of Bit. It includes the latest version of Bit pre-installed.
  • bare-scope container is an image that uses the bit-cli container and provides a bare scope.

If you prefer building your own image, you can use this base dockerfile as a starter:

FROM node:12.22.0
USER root

RUN npm i @teambit/bvm -g
RUN bvm upgrade
ENV PATH=$PATH:/root/bin

# increase memory to avoid 137 error code
ENV NODE_OPTIONS=--max_old_space_size=4096

RUN bit config set analytics_reporting false
RUN bit config set no_warnings false
RUN bit config set interactive false
RUN bit config set error_reporting true

ARG SCOPE_PATH=/root/remote-scope
RUN bit init --bare
CMD bit start

Hosting scope on a container

Start by using the bitcli/bit-server to setup a scope:

docker run -it -p {host-port}:3000 bitcli/bit-server:latest

Now open your browser and go to:


To export components to the scope, add it as a remote to your workstation:

bit remote add http://localhost:{host-port}

In your project's workspace.json file configure the defaultScope according to the scope name.
Use the export command to share your components:

bit export

Managing scopes and storage

Using specific version of bit on the bit server

Set a specific version for your server by using the BIT_VERSION argument:

docker build -f ./Dockerfile-bit-server --build-arg BIT_VERSION={version} -t bitcli/bit-server:{version} .

Change bare scope name and location on the server container

The scope name is defined by the folder name of the containing scope (remote-scope by default). This name is then later used for setting it up in the workspace.jsonc file. In case you want to change it you can pass the build arg called SCOPE_PATH like --build-arg SCOPE_PATH=/root/custom-remote-scope

Using volume to make sure data is persisted

To persist the scope data, you need the scope folder to be mounted from the host. You can use bind mounts for example:

docker run -it -v {scope-path-on-host}:/root/remote-scope -p {host-port}:3000 bitcli/bit-server:latest

It's recommended to use volumes or have an orchestrator like kubernetes handle mounts.

Single storage

Bit is using different in memory cache mechanisms. Mounting the same storage directory to different instances of the same container, may produce unexpected results.

Combining scope volume with scope name/location

When combining a change of the scope name/location and volume, you have to make sure the location provided in the SCOPE_PATH in the build arg is matching the target in the volume:

docker run -it -v {scope-path-on-host}:/root/custom-remote-scope -build-arg SCOPE_PATH=/root/custom-remote-scope -p {host-port}:3000 bitcli/bit-server:latest

See the /root/custom-remote-scope is used both in the -v arg after the : and as the SCOPE_PATH value.

Watch bit server logs on host machine

Since the bit start command at the moment can't be run as detached, you will need a way to run it as the main command and to monitor the logs at the same time.

You can mount the logs directory on the container to a directory in the host.

For example:

docker run -it -v {logs-dir-on-host}:/root/Library/Caches/Bit/logs -p {host-port}:3000 bitcli/bit-server:latest

It's recommended to use tmpfs-mounts.

Publish component packages to npm registry

A Scope handles export and import operations. To make you components installable as packages (npm install/bit install) configure them to be published to a package registry.

Bit Cloud as a package registry

Components exported to scopes hosted on Bit Cloud can be installed from Bit Cloud (no need for additional configuration).