GitHub

How to run your build locally in Docker

To be able to run your Linux stack builds locally, you’ll need docker:

In this guide, we’ll use this Bitrise Android sample project.

Large images ahead

The official Bitrise Docker images are quite large because they include a wide variety of preinstalled tools. You’ll need at least 20-25 GB FREE DISC SPACE!

If you’re not familiar with the Bitrise CLI, you should try that first. You don’t have to master the CLI, if you know what bitrise run WORKFLOW does, that should be enough for this tutorial.

Downloading Docker images from quay.io

  1. Install docker.
  2. Make sure you have your bitrise.yml in your repository.

    You don’t have to commit it, but the file must exist in your repository’s root directory.

  3. cd into your repository’s directory on your Mac/Linux.
  4. Pull the image from its registry:

    docker pull quay.io/bitriseio/android:latest
    
  5. Run the following command:

    docker run --privileged --env CI=false --volume "$(pwd):/bitrise/src" --volume "/var/run/docker.sock:/var/run/docker.sock" --rm quay.io/bitriseio/android:latest bitrise run WORKFLOW`
    

    If you want to just jump into the container and experiment inside, you can replace --rm quay.io/bitriseio/android:latest bitrise run WORKFLOW with -it quay.io/bitriseio/android:latest bash to start an interactive bash shell inside the container. For example:

    docker run --privileged --env CI=false --volume "$(pwd):/bitrise/src" --volume "/var/run/docker.sock:/var/run/docker.sock" -it quay.io/bitriseio/android:latest bash
    

    In general, if your project is an Android project but you don’t use Android NDK, to preserve precious disk space, you should use the quay.io/bitriseio/android docker image. You can find other official Bitrise docker images on our Quay page. In this example, we’re using the quay.io/bitriseio/android one.

  6. Download docker images from the Quay:

    docker pull quay.io/bitriseio/android:latest`
    

    Be aware that this can take quite a bit of time, as this image is over 10 GB. If the download fails or hangs, you can restart it any time by running the same command again.

  7. Download your Bitrise build configuration (bitrise.yml) to the root directory of your repository.

    You can download your project’s bitrise.yml from the bitrise.yml tab of your Workflow Editor on bitrise.io.

  8. In your Terminal / Command Line go to (cd) the root directory of your repository. Check if your bitrise.yml is at this location.

If you try to reproduce an issue, you should git clone your repository into a NEW DIRECTORY, so that the directory will only contain the files which are committed into the repository! It’s a frequent reproducibility issue that you try to run the commands in your normal working directory, where you most likely have files which are not committed into your repository, for example, files which are in .gitignore.

Running your builds

Run your build with the following command:

docker run --privileged --env CI=false --volume "$(pwd):/bitrise/src" --volume "/var/run/docker.sock:/var/run/docker.sock" --rm quay.io/bitriseio/android:latest bitrise run WORKFLOW

This command will share the current directory (the directory of your repository) as a shared volume with the docker container, and will make it available inside the container at the path /bitrise/src.