Overview
This architecture replaces self-managed Elasticsearch and database instances with OCI Search with OpenSearch and OCI Database with PostgreSQL, reducing operational complexity while meeting the strict requirements of Bitbucket 9.x and later versions. The benefits of this approach include built-in fault tolerance, automated security patching, automated rolling upgrades, and automated vertical and horizontal scalability for compute, memory, and storage.
Architecture
Bitbucket Data Center requires a multi-node cluster for high availability. This architecture shows a robust deployment where application nodes are distributed across availability domains, or fault domains for single AD regions, connected to managed backend services for search, metadata, and shared storage.
The following diagram illustrates this reference architecture.
bitbucket-opensearch-arch-oracle.zip#GUID-C1306B2B-C83C-448F-88BD-CD3BF09CD624
The architecture consists of a public-facing flexible load balancer that directs traffic to a cluster of Bitbucket application nodes in a private subnet. These nodes interact with OCI Search with OpenSearch for code indexing and OCI Database with PostgreSQL for system metadata. To ensure that all nodes see the same repository data, OCI File Storage is used as the shared file system.
This architecture has the following components:
- OCI region
An OCI region is a localized geographic area that contains one or more data centers, hosting availability domains. Regions are independent of other regions, and vast distances can separate them (across countries or even continents).
- Tenancy
A tenancy is a secure and isolated partition that Oracle sets up within Oracle Cloud when you sign up for OCI. You can create, organize, and administer your resources on OCI within your tenancy. A tenancy is synonymous with a company or organization. Usually, a company will have a single tenancy and reflect its organizational structure within that tenancy. A single tenancy is usually associated with a single subscription, and a single subscription usually only has one tenancy.
- OCI virtual cloud
network and subnet
A virtual cloud network (VCN) is a customizable, software-defined network that you set up in an OCI region. Like traditional data center networks, VCNs give you control over your network environment. A VCN can have multiple non-overlapping classless inter-domain routing (CIDR) blocks that you can change after you create the VCN. You can segment a VCN into subnets, which can be scoped to a region or to an availability domain. Each subnet consists of a contiguous range of addresses that don't overlap with the other subnets in the VCN. You can change the size of a subnet after creation. A subnet can be public or private.
- Availability domain
Availability domains are standalone, independent data centers within a region. The physical resources in each availability domain are isolated from the resources in the other availability domains, which provides fault tolerance. Availability domains don’t share infrastructure such as power or cooling, or the internal availability domain network. So, a failure at one availability domain shouldn't affect the other availability domains in the region.
- Fault domain
A fault domain is a grouping of hardware and infrastructure within an availability domain. Each availability domain has three fault domains with independent power and hardware. When you distribute resources across multiple fault domains, your applications can tolerate physical server failure, system maintenance, and power failures inside a fault domain.
- Dynamic routing gateway
(DRG)
The DRG is a virtual router that provides a path for private network traffic between VCNs in the same region, between a VCN and a network outside the region, such as a VCN in another OCI region, an on-premises network, or a network in another cloud provider.
- Load balancer
Oracle Cloud Infrastructure Load Balancer provides automated traffic distribution from a single entry point to multiple servers.
- OCI Site-to-Site VPN
OCI Site-to-Site VPN provides IPSec VPN connectivity between your on-premises network and VCNs on OCI. The IPSec protocol suite encrypts IP traffic before the packets are transferred from the source to the destination and decrypts the traffic when it arrives.
- OCI FastConnect
Oracle Cloud Infrastructure FastConnect creates a dedicated, private connection between your data center and OCI. FastConnect provides higher-bandwidth options and a more reliable networking experience when compared with internet-based connections.
- Internet
gateway
An internet gateway allows traffic between the public subnets in a VCN and the public internet.
- Service
gateway
A service gateway provides access from a VCN to other services, such as Oracle Cloud Infrastructure Object Storage. The traffic from the VCN to the Oracle service travels over the Oracle network fabric and does not traverse the internet.
- OCI File Storage
Oracle Cloud Infrastructure File Storage provides a durable, scalable, secure, enterprise-grade network file system. You can connect to OCI File Storage from any bare metal, virtual machine, or container instance in a VCN. You can also access OCI File Storage from outside the VCN by using Oracle Cloud Infrastructure FastConnect and IPSec VPN.
- OCI Block Volumes
With Oracle Cloud Infrastructure Block Volumes, you can create, attach, connect, and move storage volumes, and change volume performance to meet your storage, performance, and application requirements. After you attach and connect a volume to an instance, you can use the volume like a regular hard drive. You can also disconnect a volume and attach it to another instance without losing data.
- Managed service
A managed service provides specific functionality without requiring you to perform maintenance tasks related to optimizing performance, availability, scaling, security, or upgrading. A managed service enables you to focus on delivering features for your customers instead of worrying about the complexity of operations. A managed service provides a scalable and secure component for cloud-native development. Use managed services to develop and run your app and to store its data. You get best-in-class solutions without needing expertise in each domain to build and operate your app.
- OCI Compute
With Oracle Cloud Infrastructure Compute, you can provision and manage compute hosts in the cloud. You can launch compute instances with shapes that meet your resource requirements for CPU, memory, network bandwidth, and storage. After creating a compute instance, you can access it securely, restart it, attach and detach volumes, and terminate it when you no longer need it.
- OCI Database with PostgreSQL
Oracle Cloud Infrastructure Database with PostgreSQL is a managed PostgreSQL service that frees up your team from routine tasks, such as patching and backups. Its standout feature is Oracle Cloud Infrastructure Database Optimized Storage, which boosts system resilience and performance and allows for independent scalability of storage. OCI Database with PostgreSQL also provides enhanced data security with end-to-end encryption.
- Oracle AI Database 26ai
Oracle AI Database 26ai with AI Vector Search lets you query data by meaning rather than keywords. Vector representations (embeddings) capture the semantics of text, images, audio, and more so you can find similar content efficiently. Built-in SQL distance functions allow similarity searches using vectors. You can combine semantic similarity and other search criteria to ground large language models (RAG) for more accurate and relevant answers.
- OCI Search with OpenSearch
OCI Search with OpenSearch is a managed service that you can use to build in-application search solutions based on OpenSearch. Search large datasets and return results in milliseconds, without the requirement to manage infrastructure. OpenSearch offers observability features for metrics, traces, and log analysis.
- Oracle Services Network
The Oracle Services Network (OSN) is a conceptual network on OCI that is reserved for Oracle services. These services have public IP addresses that you can reach over the internet. Hosts outside Oracle Cloud can access the OSN privately by using Oracle Cloud Infrastructure FastConnect or VPN Connect. Hosts in your VCNs can access the OSN privately through a service gateway.
Recommendations
OCI Load Balancer
OCI Load Balancer distributes HTTPS (Port 443) and SSH (Port 7999) traffic. It handles SSL termination, ensuring that the application nodes receive decrypted traffic, which reduces their CPU overhead. For Bitbucket Data Center, Session Persistence (Sticky Sessions) using HTTP cookies is required to ensure users remain connected to the same node throughout their session.
OCI Compute Instances
High-performance VMs (typically E5) running the Bitbucket application. These nodes are configured as a cluster to provide redundancy and horizontal scaling. The mesh cluster is a dedicated high IO compute cluster with locally attached NVMe Storage (VMDenseIO) or a network attached block volume with very high volume performance units (VPUs). The mesh stores the code repository and is recommended for low latency requirements.
Database
Bitbucket uses OCI Database with PostgreSQL to store pull requests, user permissions, and repository metadata. Alternatively, you can use an Oracle AI Database.
OpenSearch provides the search engine required for Bitbucket's code search functionality. Because Bitbucket 9.x requires OpenSearch, using the OCI managed service removes the burden of cluster patching, scaling, and indexing maintenance.
Network
For Atlassian Bitbucket Data Center, we recommend a four-subnet strategy to ensure maximum security and traffic isolation:
- Public Subnet: Hosts the Load Balancer to manage external incoming traffic.
- Private App Subnet: Hosts the Bitbucket Application compute instances.
- Private Mesh Subnet: Hosts the Bitbucket Mesh compute cluster with 1-to-1 attached high-performance block volumes for Git processing.
- Private Data Subnet: Hosts managed services, including OCI Search with OpenSearch, OCI Database with PostgreSQL, and OCI File Storage mount targets.
Considerations
Performance
- Storage Throughput: Bitbucket is I/O intensive. While FSS is excellent for sharing data, this architecture uses Bitbucket Mesh (Atlassian's sidecar for Git processing) on OCI Block Volumes for environments with very high repository write concurrency.
- Network Latency: Ensure all managed services and compute nodes reside in the same VCN and, where possible, the same Availability Domain to minimize latency during search indexing and database transactions.
Scalability
Use OCI Compute Instance Pools to add or remove Bitbucket nodes as your developer headcount or agent count changes.
Version compatibility
Ensure the version of your databases matches the recommendation for Bitbucket Data Center. That is, OpenSearch versions 2.11 to 2.19, PostgreSQL version 16 or 17, and Oracle Database version 19c or 26ai.
Availability
To ensure maximum uptime and accessibility, we recommend deploying production clusters with a minimum of three nodes: one primary node and two replica nodes. OCI automatically distributes these nodes across availability domains or fault domains in an OCI region to eliminate downtime arising from single-point failures. In the event of a node failure, OCI automatically provisions a replacement node to restore the cluster size. Services availability is further guaranteed through these automated actions:
- OCI Compute: By distributing Bitbucket compute nodes across different fault domains, you protect the application against unexpected hardware failures or maintenance.
- OCI Database with PostgreSQL: A replica node automatically assumes the primary role, and a replacement replica node is provisioned. A database's optimized storage ensures zero data loss in the event of a node failure, because data is replicated across regional block storage and decoupled from compute nodes.
- OCI Search with OpenSearch: A leader-eligible node is automatically promoted to leader to ensure service availability.
- OCI Database with PostgreSQL ensures automated backups and high availability.
Disaster recovery
OCI ensures business continuity for Bitbucket through the OCI backbone and Dynamic Routing Gateways (DRGs), providing private inter-region connectivity with targets of near-zero RPO and minimal RTO. You can choose between two primary paths to balance cost against recovery speed:
Option 1: Backup-Based
This cost-optimized approach provisions resources in the failover region only after a disaster is declared, focusing on a low Recovery Time Objective (RTO).
- Application: Instances are re-created with automated scripts (Terraform/Ansible) using cross-region replicated Custom Images or Boot Volume backups.
- Storage: Recovery involves creating new file systems from periodic snapshots of OCI File Storage and OCI Block Volumes copied to the secondary region.
- Database: OCI Database with PostgreSQL backups are replicated to cross-region OCI Object Storage; a new instance is provisioned and restored from these backups during failover.
- Search: OCI Search with OpenSearch cluster snapshots are stored in cross-region buckets and restored to a newly provisioned search cluster.
Option 2: Active-Passive
This strategy targets a near-zero Recovery Point Objective (RPO) through continuous data synchronization between the primary and standby regions.
- Application: Bitbucket compute nodes are maintained in a "scaled-down" state or as a preconfigured Instance Pool in the DR region for immediate activation.
- Storage: OCI File Storage replication continuously synchronizes the
shared_homedirectory (repositories and metadata) to the target region. - Database: Uses OCI Database with PostgreSQL Warm Standby and provides a remote read-replica for near-instantaneous failover.
- Search: Cross-Cluster Replication (CCR) for OCI Search with OpenSearch ensures search indexes are updated in the standby region in real-time.