How to use your own Docker image for your builds

The related guide can be found at:

This is a discussion topic for the tutorial, if you have any questions related to the tutorial this is the right place to ask!

Also, if you have any tips or tricks for others please share it here!

Note for Using custom docker image option - Which image to use?:

If you use Android tools in your build you might want to base your image on the bitriseio/docker-bitrise-base image instead of on bitriseio/docker-android, if you need a really stable environment for example. The docker-bitrise-base image should not affect your Android builds, so by building your image on top of bitriseio/docker-bitrise-base you have 100% control over which Android tools and packages are available in the environment.

If you don’t want to keep rebuilding your Android docker image every week (can be automated with Docker Hub automated builds), or you simply don’t want to be affected by the changes we do in the bitriseio/docker-android image, you can copy paste the content of the Android image’s Dockerfile, remove everything you don’t need - to make the image smaller - and use this as your own Android environment.

If all you care about is speed of builds, you should base the Android image on our Android image and set up Docker Hub automated builds, as that’s the way to leverage the pre-cached layers as much as possible. But due to the size of the Android image, if you don’t configure an automated build for it and we publish an Android image update, downloading your image (which is built on an outdated and not pre-cached version of the Android image at this point) will take more time than if you base it on the bitriseio/docker-bitrise-base image.

Setting up an automated build is still the best solution, even if you use bitriseio/docker-bitrise-base as your base image! For example the Bitrise CLI is installed and updated in the bitriseio/docker-bitrise-base image, so if you don’t keep up with our images you might not be able to use newer features!

Why isn’t Docker available in the Xamarin Stable stack?

For what do you want to use Docker on the Xamarin stack @devmeuspedidos?

Mainly because it’s not preinstalled on MacOS by default, and we didn’t think it would have significant utility on the Mac stacks, as you can only run Linux inside of docker.

But of course this can change any time if we have a reason to change it :wink:

Thanks for the swift reply.

I want to use Docker to create a disposable backend for my app, for testing purposes.

So before the Xamarin Test step, I created a Script step that pulls my backend image from our docker registry, and starts a new container bound to a certain port so my app can communicate with it.

What do you think?

Makes sense, thanks for the use case!

Sounds like an interesting idea!

For docker on mac: you should be able to install it the same way you can any other tool ->
But there’s a slight chance that there will be some complication, because Docker for Mac uses a Linux virtual machine in the background, and your builds are running in a virtual machine already. It should work, but virtualization inside virtualization can have strange side effects.

I’ll try to allocate some time to test this, if you’d have some time to play around with installing docker for mac (e.g. from brew) please share with us how it goes @devmeuspedidos!

I’ve successfully installed Docker, but when I’m going to run my container, Docker exits 1, unexpectedly. Memory issues? Can you check what could be going on? Logs show nothing.

Can you please include the script you used to install & run docker?

Nevermind, I found the problem, it was my fault. Everything is working now! Thanks!

Consider running brew cask install docker-toolbox in the baked image for Xamarin, it can be very useful to have it already installed.

Thanks for reporting the solution!

Re: having this preinstalled: I agree with you although there’s one issue right now, that Docker pushed out quite a few different solutions and docker-toolbox is not their current preferred solution. It’s the one they had before Docker for Mac. That doesn’t mean that it won’t work, but it’s probably not a good idea to preinstall a “deprecated” solution.

It’s also worth to mention that the brew maintainers keep changing the docker tools as well, AFAIK brew cask install docker is the current command which will install Docker for Mac, but might change in the future.

Once things settle we’ll definitely consider to preinstall the “winner”. In the meantime I’d suggest you to install the one which fits you the best with a Script step and simply brew .. install .. the one you like.

Is there any service that allows us to cache a public docker image on Bitrise? I’m currently using my own public docker image. It works well but it would be faster if it’s being cached by Bitrise.

At the moment, this is the very basic form of my Docker Image based on an existing Bitrise Docker Image bitriseio/docker-bitrise-base. It would be interesting to see this on the paid version if that’s possible.

1 Like

Thanks for the comment @wkd!

Not directly. You might be able to use the Build Cache feature (, but AFAIK to cache docker’s build caches you have to use special commands to tar the contexts, and then in the next build to read it back.

It’s on our list to explore the topic, I’d suggest you to create a #feature-request, to make it easier to prioritize, vote and follow the progress.

Question from a user:

Any idea why I can’t mount the Gradle cache directory into the an openjdk image?
It seems to works just fine on my laptop ( docker run ... --volume ${HOME}/.gradle/:/root/.gradle ...)


The thing is, because your build is already running in Docker (in a docker container), you can only share dirs between/through containers which are mounted as a volume from the host into the base Docker container (the one your build is running in).

The only one right now is (on the Android/Linux/Docker stacks): /bitrise

This means that if you share ${HOME}/.gradle/:/root/.gradle as a volume that won’t share the volume from the build’s container, that will share it from the host, where gradle is not installed (the only thing installed on the host is docker).

​So, if you want to share anything as a volume from your build into a container which is started by your build (e.g. with a docker run) you should share it from /bitrise. Your code by default is cloned into /bitrise/src, so you can share that directly if you want to. Otherwise, if you’d want to mount a volume into $HOME/.gradle inside the container you start, you should mount it from a /bitrise/ dir.

E.g. create a /bitrise/gradle-cache dir (or any dir under /bitrise) and then share it with --volume "/bitrise/gradle-cache:/root/.gradle" or similar.

PR to have docker for mac preinstalled:

We had to revert it due to the reasons described there, but if anyone would have the time to provide a script which solves those issue we’d be happy to add it and have Docker for Mac preinstalled!

If anyone’s interested we now have a #feature-request for preinstalling Docker on the Mac stacks:

I also shared an up to date Script based solution there which can be used on a Mac stack, where Docker is not preinstalled, to install and initialize/start Docker: