Run any Jira Data Center version with a real database directly on your own desktop

Hey Jira admins, developers and enthusiasts, would you like to know how to run any Jira version right on your local environment with a normal database like Postgres? This guide will show you how you can do it easily, without much effort or special Linux/DevOps knowledge.

Why run Jira locally?

TL;DR: for Development and Testing purposes.

Okay, so picture this: you're knee-deep in code, tweaking configurations, and fine-tuning workflows in Jira. Wouldn't it be awesome if you could do all of this without worrying about breaking something in the live system? That's where running Jira locally for development and testing comes into play, and let me tell you why it's a game-change:

1. Your Own Sandbox: Running Jira locally gives you a playground where you can experiment to your heart's content. It's like having your own sandbox. You can make changes, try out new plugins, and mess around with configurations without sweating over the consequences.
2. Speedy Iterations: Imagine this: you make a change, click a button, and bam! You see the results instantly. That's the beauty of running Jira locally. You can iterate faster, which means you can get feedback quicker and ship code faster. It's a win-win situation.
3. Save Some Bucks: Let's talk about money for a sec. Setting up a local instance of Jira with Docker won't cost you an arm and a leg. You can use your existing hardware and resources, which means you save big bucks on infrastructure costs. Who doesn't love saving money, am I right?
4. Test Like a Pro: With a local instance of Jira, you can test like a pro. You can run comprehensive tests, including integration testing and performance testing, in a controlled environment. This means you catch bugs early, squash them quickly, and deliver top-notch software every time.

So there you have it, folks! Running Jira locally for development and testing is a no-brainer. It's fast, it's flexible, and it's downright awesome.

And how are we going to do it? Docker is the answer. With Docker, we'll use public, officially supported Jira and database images, from its vendors to teardown of our local environment. It's a practical solution that streamlines the process, making it efficient and hassle-free. Let's get started with Docker and make setting up Jira locally a breeze.

Starting with Docker

Alright, before we dive into the nitty-gritty of setting up Jira locally with Docker, let's make sure we've got all our ducks in a row. Here's what you'll need:

Requirements for Running Jira Locally with Docker:

• First things first, make sure your computer meets the minimum requirements for running Docker. You'll need a decent amount of RAM (16GB is absolutely minimum, based on my experience), disk space (2-4 GB depends on Jira version and installed applications), and processing power to handle the containers like a champ.

Installation of Docker and Docker Compose:

• If you haven't already jumped on the Docker bandwagon, now's the time. Head over to the Docker website and grab the latest version of Docker for your operating system. While you're at it, don't forget to snag Docker Compose too. It's like the sidekick to Docker that makes managing multi-container applications a breeze.
• The easiest and recommended way to get Docker Compose is to install Docker Desktop. Docker Desktop includes Docker Compose along with Docker Engine and Docker CLI - https://docs.docker.com/get-docker/

Basic Understanding of Docker Concepts:

• Docker may seem like magic at first, but it's actually pretty straightforward once you wrap your head around it. Before you dive into setting up Jira with Docker, make sure you have a basic understanding of Docker concepts like containers, images, volumes, and networks. Trust me, it'll make your life a lot easier down the road.
• https://docs.docker.com/get-started/overview
• Or here is the detailed guide how to become familiar with Docker https://roadmap.sh/docker

So there you have it! With these prerequisites out of the way, you'll be ready to roll up your sleeves and get your hands dirty with setting up Jira locally using Docker. Let's do this!

The Problem

Let's start with the problem: we want to set up the latest stable version of Jira Software with a compatible PostgreSQL database. To find the latest version, check Atlassian's release notes page https://confluence.atlassian.com/jirasoftware/jira-software-release-notes-776821069.html or "Long Term Support releases" for the latest LTS version here. As of June 2024, the latest Jira Software version is 9.16.0. We'll use this version for our example, but make sure to double-check this because Atlassian releases new versions frequently.

Next, we need to find the compatible version of PostgreSQL for this Jira version. Refer to the "Supported platforms" page here. According to the documentation, "PostgreSQL 12" is the recommended version.

Now, let's put it all together.

The Solution is… docker-compose.yml

Now that we know which versions of Jira and PostgreSQL we need, it's time to set up our Docker environment. We'll use Docker Compose to manage both the Jira application and the PostgreSQL database. Here's how to create the docker-compose.yml file.

Create a New Directory: Start by creating a new directory for your project. This is where all your Docker-related files will live.

Create the docker-compose.yml file: In this directory, create a new file named "docker-compose.yml". You can do this using any text editor you prefer.

Define Services in docker-compose.yml: Open the "docker-compose.yml" file in your text editor and define the services for Jira and PostgreSQL. Here’s a basic setup:

services:
  jira:
    container_name: jira
    image: atlassian/jira-software:9.16.0 # LTS: https://www.atlassian.com/software/jira/download-archives
    depends_on:
      - jiradb
    networks:
      - jiranet
    volumes:
      - ./jira:/var/atlassian/application-data/jira
    ports:
      - '8080:8080'
    environment:
      - ATL_JDBC_URL=jdbc:postgresql://jiradb:5432/db
      - ATL_JDBC_USER=jiradbuser
      - ATL_JDBC_PASSWORD=DoNotTimeTravelTo2020!
      - ATL_DB_DRIVER=org.postgresql.Driver
      - ATL_DB_TYPE=postgres72
      - JVM_MINIMUM_MEMORY=2048m
      - JVM_MAXIMUM_MEMORY=8192m
      - ATL_PROXY_NAME=localhost
      - ATL_PROXY_PORT=8080
      - ATL_TOMCAT_SCHEME=http
    restart: unless-stopped

  jiradb:
    container_name: postgresql
    image: postgres:12
    ports:
      - 5432:5432
    networks:
      - jiranet
    volumes:
      - ./postgresql:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=jiradbuser
      - POSTGRES_PASSWORD=DoNotTimeTravelTo2020! # The same as in ATL_JDBC_PASSWORD
      - POSTGRES_DB=db
      - POSTGRES_ENCODING=UNICODE
      - POSTGRES_COLLATE=C
      - POSTGRES_COLLATE_TYPE=C
    restart: unless-stopped

networks:
  jiranet:
    driver: bridge        

Explanation of the docker-compose.yml File

Services "jira":

• image: Specifies the Jira Software image and version.
• container_name: Name of the Jira container.
• ports: Maps the container port 8080 to the host port 8080.
• environment: Sets environment variables for database connection and configuration.
• volumes: Mounts a volume to persist Jira application data.
• depends_on: Ensures that the PostgreSQL container starts before the Jira container.
• networks: Specifies the network for container communication.

Services "postgres":

• image: Specifies the PostgreSQL image and version.
• container_name: Name of the PostgreSQL container.
• environment: Sets environment variables for the PostgreSQL database (database name, user, password).
• volumes: Mounts a volume to persist data.
• networks: Specifies the network for container communication.

Networks: Defines a network for the containers to communicate.

Save and Close the File: After adding the configuration, save the "docker-compose.yml" file and close your text editor.

Running docker-compose.yml

Now that we've created our docker-compose.yml file, it's time to bring our Jira and PostgreSQL services to life. Follow these steps to run the Docker Compose setup and get your local Jira instance up and running.

Start the Services: In your terminal, navigate to the directory where your docker-compose.yml file is located. Use the following command to start the services defined in the file:

docker compose up -d        

The "up" command tells Docker Compose to start the services.

The "-d" flag runs the containers in the background (detached mode), allowing you to use your terminal for other tasks.

Access Jira: With the containers running, open your web browser and navigate to https://localhost:8080. This is where you'll find your Jira instance.

The first time you access Jira, you'll need to go through the initial setup process. Follow the on-screen instructions to configure your Jira instance. Stay patient, depending on your laptop's CPU and RAM, the process might take some time. Wait for the loading process to complete and for the system to redirect you to the next step of the configuration.

Stopping and Restarting Services

Stopping the Services: If you need to stop the Jira and PostgreSQL containers, you can do so with the following command:

docker compose down        

This command stops and removes the containers but preserves the data in the named volumes.

Restarting the Services: To restart the services after stopping them, simply use the "docker compose up -d" command again. Your data will be preserved, and Jira will start up with the previous configuration.

Conclusion

Running Jira locally using Docker and Docker Compose offers a powerful and flexible solution for developers, admins, and enthusiasts. By encapsulating Jira and its dependencies into containers, you gain the ability to easily set up, manage, and experiment with your Jira environment without impacting production systems.

Among multiple other examples, this approach has several distinct benefits:

1. Reliance on Official Images: We use only the latest versions of official Docker images, supported by Atlassian itself. This eliminates dependencies on third-party or home-grown solutions, ensuring compatibility and stability.
2. Version Flexibility: You can easily run any version of Jira Core, Jira Software, or even Jira Service Management Data Center in your own environment. Switching between versions is straightforward, allowing for seamless testing and development across different Jira products.
3. Realistic Testing Environment: This configuration uses a real PostgreSQL database, which mimics a production-like setup. This allows Jira to communicate with the database in a manner that closely replicates real-world installation scenarios, providing a more accurate testing and development environment.

I'd love to hear from you! Share your thoughts about running Jira with PostgreSQL using Docker Compose. Do you have any ideas to optimize this configuration? Your feedback and suggestions can help others in the community improve their setups as well.