Architecting Enterprise Knowledge Bases with Atlassian Confluence on Docker

The deployment of Atlassian Confluence via containerization represents a significant shift in how organizations manage their internal knowledge bases. By leveraging Docker, administrators can abstract the Confluence application from the underlying host operating system, ensuring a consistent environment across development, staging, and production. This architectural approach mitigates the "it works on my machine" syndrome and allows for rapid scaling and recovery. In the modern DevOps landscape, moving from traditional manual installations—which often involve complex Java Runtime Environment (JRE) configurations and manual file system permissioning—to a containerized model streamlines the lifecycle management of the application. This transition allows for immutable infrastructure patterns where updates are handled by replacing containers rather than patching live systems.

The Atlassian Official Docker Image Ecosystem

Atlassian provides official images to facilitate the deployment of Confluence. These images are designed to encapsulate the application server and the necessary dependencies to get the platform operational with minimal overhead.

The official image is available under two primary identifiers on Docker Hub: atlassian/confluence and atlassian/confluence-server. While both point to the same functional image, there is a critical administrative distinction between them. The atlassian/confluence-server tag is now considered deprecated. It is maintained exclusively for backwards-compatibility to ensure that legacy scripts and deployment pipelines do not break upon image updates. For all new installations, the shorter identifier, atlassian/confluence, is the mandated standard.

The technical requirement for running these images is a Docker version of 20.10.10 or higher. This version requirement ensures compatibility with the container runtime and the underlying storage drivers necessary for the heavy I/O operations Confluence performs during index updates and page rendering.

Technical Deployment and Resource Allocation

Launching a Confluence instance requires a precise configuration of networking and storage to ensure data persistence and accessibility.

The basic command to initialize a Confluence container is as follows:

bash docker run -v /data/your-confluence-home:/var/atlassian/application-data/confluence --name="confluence" -d -p 8090:8090 -p 8091:8091 atlassian/confluence

Breaking down this command reveals several critical technical layers:

• The -v flag creates a bind mount. In this instance, /data/your-confluence-home on the host is mapped to /var/atlassian/application-data/confluence inside the container. This is vital because containers are ephemeral; without this mount, all uploaded attachments, database configurations, and plugin data would be deleted the moment the container is stopped or updated.
• The -p 8090:8090 mapping handles the primary web traffic. Port 8090 is the default port for the Confluence application server.
• The -p 8091:8091 mapping is utilized for synchronization and clustering communication.
• The -d flag ensures the container runs in detached mode, allowing it to operate as a background service.

From a resource perspective, Confluence is a memory-intensive Java application. Atlassian recommends allocating at least 2GiB of memory to the container. If the memory limit is set too low, the Java Virtual Machine (JVM) may trigger OutOfMemoryError (OOM) kills, leading to unstable application behavior or complete crashes during the startup phase.

For users operating on macOS via docker-machine, the local localhost address may not resolve to the container. In such cases, the access URL must be constructed using the docker-machine IP:

bash http://$(docker-machine ip default):8090

Data Persistence and Home Directory Configuration

The concept of the "Confluence Home" is central to the application's stability. The CONFLUENCE_HOME environment variable defines the directory where the application stores its internal data, including the search index, cache, and user-uploaded content.

In a standard Docker deployment, mounting a host directory to the path specified by CONFLUENCE_HOME is the recommended practice. This ensures that the "state" of the application survives container restarts.

When transitioning to more complex architectures, such as Data Center mode, the requirements for storage evolve. Data Center deployments require a shared filesystem to be mounted. This is because multiple Confluence nodes must have concurrent access to the same shared home directory to synchronize attachments and plugins. The internal mount point for this shared data is configurable via the CONFLUENCE_SHARED_HOME environment variable.

Analysis of Image Tags and Versioning

Atlassian maintains a granular tagging system on Docker Hub to allow administrators to choose the specific operating system and Java version that matches their security and performance requirements.

The following table details the available image variants based on recent repository data:

The use of UBI9 (Universal Base Image 9) provides a hardened, enterprise-grade Linux environment, whereas the Ubuntu-based images provide a more common ecosystem for developers. The inclusion of JDK 21 tags indicates a move toward the latest Long-Term Support (LTS) Java release, which offers improved memory management and performance over older versions.

Confluence Data Center in Docker: Challenges and Strategies

There is a significant distinction between the "Server" (single node) and "Data Center" (clustered) versions of Confluence. According to official Atlassian guidance, Confluence Data Center is not officially supported on Docker, and consequently, there is no official "Data Center" specific image provided.

To run Confluence Data Center in a containerized environment, administrators must build their own custom images based on the Data Center installation files. This introduces several technical hurdles:

• Port Conflicts: When running multiple nodes on a single physical server, port collisions occur because every node attempts to listen on port 8090. To resolve this, administrators must either map different host ports to the container port (e.g., 8090:8090 for node 1 and 8091:8090 for node 2) or utilize a container orchestrator.
• Orchestration: For production-grade Data Center clusters, using a single docker-compose.yml file for every node is a common starting point, but transitioning to Docker Swarm or Kubernetes is recommended. This allows for the dynamic scaling of nodes and better load balancing across a distributed set of hosts.

Alternative Implementations and Third-Party Images

Beyond the official Atlassian images, the community has developed specialized images to simplify the installation process. One such example is the cptactionhank/atlassian-confluence image.

This community image is designed for rapid deployment and provides additional configuration options via environment variables to handle reverse proxy setups. This is particularly useful when Confluence is placed behind a load balancer or an Nginx proxy.

The available configuration variables for this image include:

• X_PROXY_NAME: Used to set the Tomcat Connectors ProxyName attribute.
• X_PROXY_PORT: Defines the ProxyPort attribute for the connector.
• X_PROXY_SCHEME: When set to https, this triggers the Tomcat Connectors secure=true and sets the redirectPort to the value of X_PROXY_PORT.
• X_PATH: Sets the Tomcat connectors path attribute.

The deployment command for this community image is:

bash docker run --detach --publish 8090:8090 cptactionhank/atlassian-confluence:latest

Advanced Configuration and Infrastructure as Code

For any installation that moves beyond a simple "proof of concept," the use of raw docker run commands is discouraged. The industry standard is to use docker-compose to define the infrastructure as code.

Using docker-compose provides several advantages:

• Documentation: The YAML file serves as a living document of the system configuration.
• Repeatability: Entire environments can be torn down and rebuilt with a single command: docker-compose up -d.
• Dependency Management: It allows for the easy addition of a database container (such as PostgreSQL or MySQL) and ensures that the Confluence container only starts after the database is healthy.

In a typical docker-compose setup, the volumes section replaces the -v flag, and the environment section replaces the -e flags, providing a clean and maintainable structure.

Comparison of Installation Methods

The choice of installation method depends on the level of control required and the intended environment.

Conclusion

Deploying Atlassian Confluence via Docker transforms the software from a cumbersome, stateful installation into a flexible, portable service. The transition from atlassian/confluence-server to atlassian/confluence reflects the ongoing evolution of the product's delivery model. While the official images provide a robust foundation for single-node "Server" installations, the "Data Center" path requires a more sophisticated approach involving custom image creation and careful orchestration to handle shared storage and port conflicts.

The critical success factors for a containerized Confluence deployment are the strict adherence to memory allocations (minimum 2GiB), the implementation of persistent volume mounts for the CONFLUENCE_HOME directory, and the use of version-specific tags to ensure stability. Whether using the official UBI9 images for enterprise security or community images for proxy flexibility, the containerized approach significantly reduces the time-to-value for organizations seeking to implement a centralized knowledge management system.

Sources

1. Atlassian Confluence Server Docker Hub
2. Atlassian Confluence Docker Hub
3. Confluence Installation Guide
4. Tomica Blog: Atlassian Confluence in Docker
5. Atlassian Community: Official Confluence Data Center Docker image
6. GitHub: cptactionhank/docker-atlassian-confluence
7. Atlassian Confluence Docker Tags