Debug your pipelines locally with Docker

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

You can test your Bitbucket Pipelines build locally with Docker. For example, you can check whether your Docker image suits the needs of your setup.

See also:

Before you begin

Prepare your local environment. Make sure you have a local copy of your Bitbucket repository with your bitbucket-pipelines.yml file ready.

Show me how to clone a repo

In short:

$ cd /Users/myUserName/code

$ git clone git@bitbucket.org:myBBUserName/localDebugRepo.git

For the detailed guidelines, see Clone a repository.


Example

In this scenario, we'll be testing the following bitbucket-pipelines.yml file:

bitbucket-pipelines.yml
# You can use a Docker image from Docker Hub or your own container
# registry for your build environment.
image: python:2.7
 
pipelines:
  default:
    - step:
        script: # Modify the commands below to build your repository.
          - python --version
          - python myScript.py


You can check your bitbucket-pipelines.yml file with our online validator.


Step 1: Install Docker on your machine

The installation procedure differs depending on the operating system that you want to use. Follow the installation guidelines provided by Docker: https://docs.docker.com/engine/installation/

Result

Go to the terminal and run:

$ docker -v

If you have SSH installed, the command returns the version details.


Step 2a: Build a Docker image

Once your Docker installation is in place, you can build a docker image

$ docker build --memory=1g --memory-swap=1g -t account/imageName:tag -f my.dockerfile .


where:

docker build

Specifies you wish to build a docker image


--memory=4g --memory-swap=4g

Builds the container with a 1GB of memory and no swap space, which simulates the memory restrictions in Pipelines (all 2 flags are needed).

Set the memory limit when debugging locally to replicate Pipelines as closely as possible and so discover whether you are hitting Pipelines memory limits. Many issues with failing pipelines that pass locally are due to memory constraints.

Read more about memory management in the Docker docs.

macOS (OS X)

Use the docker stats command to check the actual memory limit of the container.

You can modify the default memory settings in the status bar ( > Preferences > Advanced).

-t accountName/imageName:tag

Creates an image for the account with the name provided, with the image name provided and with the tag provided.

-f my.dockerfile

Specifies the name of the docker file to use when building the image

. Specifies the directory (currently the current one) to use as the root of the docker build context

Step 2b: Run commands in your Docker container

Once your Docker installation is in place, you can run commands in your local Docker container:

$ docker run -it --volume=/Users/myUserName/code/localDebugRepo:/localDebugRepo --workdir="/localDebugRepo" --memory=4g --memory-swap=4g --memory-swappiness=0 --entrypoint=/bin/bash python:2.7


where:

docker run -it

Runs a Docker container with a TTY and with STDIN open. It means that the container opens in an interactive mode and you can run commands in it.

--volume=/Users/myUserName/code/localDebugRepo:/localDebugRepo

Mounts the local directory called /Users/myUserName/code/localDebugRepo inside the container as /localDebugRepo.

Note

Any changes to the repository content that occur within the container are reflected in the local clone of your repository.

View more

The command runs with a default setting, which grants the container read and write permissions to the repository. You can limit the access to the local directory to read only by adding :ro at the end of the command:

-- volume=/Users/myUserName/code/localDebugRepo:/localDebugRepo:ro

--workdir="/localDebugRepo"

Sets the directory in which you want to start. This is the directory in which you run the commands. By default, it's the root directory of the container.

--memory=4g --memory-swap=4g --memory-swappiness=0

Runs the container with 4 GB of memory and no swap space, which simulates the memory restrictions in Pipelines (all 3 flags are needed).

Set the memory limit when debugging locally to replicate Pipelines as closely as possible and so discover whether you are hitting Pipelines memory limits. Many issues with failing pipelines that pass locally are due to memory constraints.

Read more about memory management in the Docker docs.

macOS (OS X)

Use the docker stats command to check the actual memory limit of the container.

You can modify the default memory settings in the status bar ( > Preferences > Advanced).

python: 2.7

The Docker image that you want to run. You probably want to use the image that you specified in your bitbucket-pipeline.yml file. For more information, see Use Docker images as build environments.

--entrypoint=/bin/bash

Starts a bash prompt


Result

The Docker image is running and you can see the ID, for example:

root@1af123ef2211:/localDebugRepo

You're inside of your working directory and you can start executing commands.


Step 3: Test Bitbucket Pipelines in your local setup

At this stage, we have the python:2.7 container open and we're inside the repository directory.

You can:

  • run individual commands of your bitbucket-pipelines.yml to test them

  • configure tools inside the container

Once you get things working as needed in your local Docker container:

  1. Note the changes.

  2. Add them to your bitbucket-pipelines.yml file.

  3. Push them back up to Bitbucket to build in Pipelines.



If you want to try building your own Docker container, check out How do I create a docker image for Bitbucket Pipelines?

Examples

The examples below show how you can test the configuration of your bitbucket-pipelines.yml file that we mentioned at the beginning of this guide.

Show me the file again
bitbucket-pipelines.yml
# You can use a Docker image from Docker Hub or your own container
# registry for your build environment.
image: python:2.7
 
pipelines:
  default:
    - step:
        script: # Modify the commands below to build your repository.
          - python --version
          - python myScript.py


Check the python version:

$ python --version

Output:

Python 2.7.11


Run one of your python scripts:


$ python myScript.py

Note: This example works only if you have the myScript.py script in the repo.

Output:

Python 2.7.11


Configure things as usual inside the container:


$ pip install scipy

Output:

Collecting scipy
   Downloading scipy- 0.17 . 1 -cp27-cp27mu-manylinux1_x86_64.whl ( 39 .5MB)
     100 % |████████████████████████████████|  39 .5MB 34kB/s
Installing collected packages: scipy
Successfully installed scipy- 0.17 . 1
Last modified on Jan 31, 2018

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.