The integration of Docker with Bitbucket represents a multifaceted technical landscape, encompassing both the deployment of the Bitbucket application itself as a containerized service and the utilization of Docker containers as the foundational execution environment for Bitbucket Pipelines. For the enterprise architect or the DevOps engineer, understanding the nuances of these two distinct domains—self-hosted infrastructure and CI/CD orchestration—is critical for ensuring system stability, scalability, and build performance. Whether deploying an on-premises Git management solution via the official Atlassian images or optimizing a container-based build pipeline, the technical requirements vary significantly. This exploration delves into the specific Docker images provided by Atlassian, the architectural constraints of the Bitbucket Pipelines environment, and the operational best practices required to maintain a production-grade deployment.
Atlassian Bitbucket Docker Image Architecture
Atlassian provides official Docker images to facilitate the rapid deployment of Bitbucket as an on-premises source code management solution. This approach allows organizations to maintain the security and speed of Git while retaining full control over the underlying server infrastructure.
The image is designed to be enterprise-grade, providing a secure and fast environment for managing repositories and configuring fine-grained permissions. From a technical perspective, the transition from traditional VM-based installations to Docker containers reduces the overhead associated with operating system management and simplifies the process of version upgrades and environment replication.
Image Naming and Versioning Transitions
A critical point of administrative attention is the naming convention of the official images. There are two primary image identifiers associated with this software: atlassian/bitbucket and atlassian/bitbucket-server.
Historically, these two names pointed to the exact same image. However, a significant change occurred on February 15, 2024. After this date, the atlassian/bitbucket-server image was deprecated. While it remains available for backwards-compatibility purposes, it no longer receives updates, which includes both existing and new tags.
The impact of this change is significant for maintenance schedules. Organizations continuing to use the -server suffix will find themselves on a stagnant version of the software, missing critical security patches and feature updates. Consequently, the mandatory technical migration path for all new installations and existing upgrades is to transition to the shorter atlassian/bitbucket image.
The OpenSearch Embedded Component and Shutdown Dynamics
The Docker images for Bitbucket include an embedded OpenSearch server to provide search functionality within the application. However, the implementation of this embedded server varies by version:
- Only Bitbucket versions lower than 10 include an embedded search server.
- By default, the image will start both the Bitbucket application and the embedded OpenSearch instance for the sake of backwards compatibility.
From a technical layer, this embedded configuration is explicitly discouraged, particularly in clustered environments. The embedded OpenSearch instance has known issues regarding the shutdown process, which can lead to unclean exits and potential data corruption or resource leaks. The recommended architectural pattern is to decouple the search functionality by running a separate OpenSearch instance, potentially in its own dedicated Docker container. This separation ensures that the application server and the search cluster can be scaled and managed independently, improving the overall resilience of the stack.
Production Deployment and Tagging Strategy
When deploying Bitbucket in a production environment, the choice of image tag is paramount. Atlassian strongly recommends against using the latest tag.
The use of latest introduces non-deterministic deployments; an automated restart or a new deployment could pull a version of the image that contains breaking changes or unstable features. By using a specific version tag, administrators ensure that the environment is immutable and predictable. This allows for a controlled upgrade path where the new version is tested in a staging environment before being promoted to production.
Resource Allocation and Network Configuration
Running Bitbucket in a container requires specific resource considerations to prevent application instability and "Out of Memory" (OOM) kills.
The recommended minimum memory allocation is 2GiB. This allocation is necessary to accommodate both the Java application server and the various Git processes that execute during repository operations. Insufficient memory can lead to severe performance degradation during high-concurrency events or large repository clones.
Regarding networking, the application is accessible by default at http://localhost:7990. However, specific environments require different access patterns:
- Standard Docker: Access via
http://localhost:7990. - Docker-machine on macOS: Access via
http://$(docker-machine ip default):7990. - Reverse Proxy Setup: If the container is placed behind a reverse proxy, additional configuration options must be specified to ensure Bitbucket is aware of the proxy setup, preventing issues with URL redirection and header propagation.
Analysis of Available Image Tags and Specifications
The atlassian/bitbucket image is distributed with a variety of tags to support different operating system bases and Java Development Kit (JDK) versions. The following table provides a technical breakdown of available tags and their properties based on recent Docker Hub data.
| Tag | Architecture | Image Size (approx.) | Notes |
|---|---|---|---|
| 9.3.2-ubi9-jdk17 | linux/amd64, linux/arm64 | 810.45 MB - 813.07 MB | Updated recently; supports ARM64 |
| 9.6.0-ubi9 | linux/amd64 | 824.05 MB | Standard UBI9 base |
| 9.6.0-ubi9-jdk17 | linux/amd64 | Not specified | JDK 17 optimized |
| 9.4.0-ubi9 | linux/amd64 | 817.09 MB - 819.71 MB | Stable version |
| 9.1.0-ubi9 | linux/amd64 | 790.84 MB - 793.34 MB | Legacy UBI9 |
| 8.19.21-ubi9-jdk17 | linux/amd64 | 806.28 MB | JDK 17 support |
| 8.19.21-ubi9 | linux/amd64 | Not specified | Standard UBI9 |
The transition to UBI9 (Universal Base Image 9) and JDK 17 reflects Atlassian's alignment with modern enterprise Linux standards and the long-term support (LTS) cycle of the Java ecosystem. The availability of linux/arm64 for version 9.3.2 allows for deployment on ARM-based cloud instances, which often provide a better price-to-performance ratio.
Bitbucket Pipelines and Docker Integration
Beyond the application itself, Bitbucket Pipelines utilizes Docker to create the environments where code is built, tested, and deployed. In this context, Docker is not the application being hosted, but the engine driving the CI/CD process.
The Build Environment Concept
Every build in Bitbucket Pipelines runs inside a Docker container. This container defines the entire toolset available to the developer. Users have two primary paths for defining this environment:
- Default Image: If no image is specified, Bitbucket uses
atlassian/default-image:latest. - Custom Image: Users can specify public or private images from Docker Hub, AWS, GCP, or other internet-accessible self-hosted registries. It is important to note that Bitbucket Pipelines cannot access images that are not available via the internet.
Default Image Specifications
The default images provided by Atlassian are mapped to specific Ubuntu versions. Choosing the correct version ensures compatibility with the tools required for the build.
| Image Tag | Platform | Recommended Use Case |
|---|---|---|
| atlassian/default-image:1 | Ubuntu 14.04 | Legacy builds |
| atlassian/default-image:2 | Ubuntu 16.04 | Legacy builds |
| atlassian/default-image:3 | Ubuntu 20.04 LTS | Standard builds |
| atlassian/default-image:4 | Ubuntu 22.04 LTS | Recommended for self-hosted runners |
| atlassian/default-image:5 | Ubuntu 24.04 LTS | Recommended for cloud-hosted runners |
The administrative recommendation is to move away from these default images once the initial pipeline is functional. Default images are updated infrequently to maximize compatibility, meaning they may lack the latest versions of compilers or libraries. Using a specific, custom-built image reduces the "bloat" of unnecessary tools and increases the security posture of the build environment.
Executing Docker Commands within Pipelines
Bitbucket Pipelines provides a built-in mechanism to run Docker commands (such as docker build or docker push) inside a pipeline step. This is achieved by enabling the Docker service.
Technically, this is implemented by mounting the Docker CLI into the container running the pipeline. Because Docker is a default service, it does not need to be declared as an external service; it is simply added to the services section of the bitbucket-pipelines.yml file.
Example configuration for a Docker build:
yaml
pipelines:
branches:
master:
- step:
name: Build with Docker
script:
- docker build .
services:
- docker
Advanced Docker Features and BuildKit
For users requiring more advanced build capabilities, Bitbucket Pipelines supports BuildKit. BuildKit is a next-generation build engine for Docker that offers faster build times and more efficient image layering.
To enable BuildKit, the environment variable DOCKER_BUILDKIT=1 must be exported within the pipeline script.
Example with BuildKit enabled:
yaml
pipelines:
branches:
master:
- step:
name: Build with Docker
script:
- export DOCKER_BUILDKIT=1
- docker build .
services:
- docker
Critical Limitations of Bitbucket Pipelines Docker Builds
While the integration allows for image creation, there are severe technical limitations that can make the process slow and inefficient for complex projects.
Multi-platform and Buildx Constraints
Bitbucket Pipelines lacks native support for multi-platform builds. This means developers cannot easily build images for multiple architectures (e.g., both amd64 and arm64) within a single pipeline execution. The lack of buildx support further limits the ability to utilize advanced image manipulation and distribution features.
Caching Inefficiencies
One of the most significant bottlenecks in Bitbucket Pipelines is the caching mechanism. The standard caching provided by the platform is often practically unusable for Docker image builds. Docker relies on layer caching to avoid rebuilding unchanged parts of an image; however, the way Bitbucket Pipelines handles the filesystem between steps often prevents the efficient reuse of these layers, leading to "cold" builds that take significantly longer than necessary.
Performance Impact and External Solutions
The combination of limited caching and the lack of advanced BuildKit features results in a "slow and painful" build experience. To resolve these issues, some organizations turn to remote Docker image building services like Depot.
Depot integrates with Bitbucket Pipelines to provide:
- Cloud builders for both Intel and ARM architectures.
- High-speed Docker layer caching stored on SSDs.
- Reported speed increases of up to 40x compared to native Bitbucket Docker builds.
Conclusion
The deployment and utilization of Docker within the Bitbucket ecosystem require a nuanced understanding of both application-level containerization and pipeline-level orchestration. For those deploying the Bitbucket application, the transition to the atlassian/bitbucket image and the decoupling of OpenSearch are non-negotiable requirements for maintaining a stable, production-ready environment. The allocation of at least 2GiB of memory and the use of specific version tags are the primary safeguards against runtime instability and non-deterministic updates.
Simultaneously, for those utilizing Bitbucket Pipelines, the shift from default images (atlassian/default-image) to custom, lean images is a critical step in optimizing build times and security. While the integration of the Docker service allows for the execution of docker build commands, the inherent limitations regarding multi-platform support and layer caching present a ceiling for performance. The use of BuildKit via DOCKER_BUILDKIT=1 provides a marginal improvement, but for high-scale enterprise needs, offloading the build process to a dedicated remote builder is the only viable path to achieving rapid iteration cycles. Ultimately, the success of a Bitbucket Docker implementation depends on the transition from "convenience" configurations (like the latest tag or default images) to "explicit" configurations (specific tags and custom build environments).