Jenkins Installation on EC2 Instance Troubleshooting Journey: A Detailed Guide

1. Introduction

When I started learning Jenkins, my very first step was to install it on an EC2 instance. While setting it up, I encountered several startup errors and connection issues. By carefully reviewing logs and configurations, I discovered that the root problem was due to an unsupported Java version. This guide walks through the process I followed, the key lessons learned, and best practices to help newcomers troubleshoot similar issues.

---

2. The Issue

A. Service Startup Failures

• Symptoms:

  • Jenkins repeatedly failed to start.

  • Using commands like systemctl status jenkins.service, sudo systemctl start jenkins and journalctl -xeu jenkins.service revealed jenkins service could not be found and there are multiple restart attempts.

    

• 

• 

• Key Error:

  • The logs stated:
    "Running with Java 11 from /usr/lib/jvm/java-11-openjdk-amd64, which is older than the minimum required version (Java 17)."

B. Browser Connection Error

• Symptom:

  • A “connection not secure” warning appeared when accessing Jenkins via HTTPS.

• Observation:

  • Switching to HTTP confirmed that this was a secondary issue, while the primary problem was the Java version mismatch.

---

3. Step-by-Step Debugging Process

Step 1: Review Logs and Check Service Status

• Actions:

  • Executed:

      sudo systemctl status jenkins.service
      sudo journalctl -xeu jenkins.service
      sudo journalctl -u jenkins --no-pager | tail -50
    

• Findings:

  • The logs from sudo journalctl -u jenkins --no-pager | tail -50 indicated repeated restarts and pointed to Jenkins running on Java 11.

Step 2: Verify the Installed Java Version

• Action:

  • Ran:

      java -version
    

• Outcome:

  • The output confirmed that Java 11 was being used, which is below the required version.

Step 3: Identify the Compatibility Mismatch

• Observation:

  • Official Jenkins documentation now requires Java 17 or newer.

• Mistake:

  • Initially, I attempted to reinstall Jenkins without addressing the Java version issue—this approach didn’t work until I focused on the underlying mismatch.

Step 4: Upgrade to Java 17

• Actions:

  1. Install Java 17:

      sudo apt update
      sudo apt install openjdk-17-jdk -y
     

     Set Java 17 as Default:

      sudo update-alternatives --config java
     

Verification:

• Running java -version now shows Java 17.

Step 5: Reload and Restart Jenkins

• Actions:

    sudo systemctl daemon-reload
    sudo systemctl restart jenkins
    sudo systemctl status jenkins
  

• Outcome:

  • Jenkins started successfully using Java 17.

Step 6: Address Browser Access Issues

• Tip:

  • If you see an SSL warning via HTTPS, try accessing Jenkins via HTTP (e.g., http://<server-ip>:8080) until SSL settings are properly configured.

---

4. Lessons Learned

• Review Logs First:
  Always inspect logs using tools like journalctl and systemctl to identify the root cause before making major changes.

• Verify System Requirements:
  Confirm that your environment meets all software requirements. In this case, ensuring Jenkins runs on Java 17 was crucial.

• Incremental Troubleshooting:
  Tackle one issue at a time—check service status, then verify the Java version, and finally restart Jenkins.

• Avoid Premature Reinstallation:
  Reinstalling Jenkins without addressing the Java version mismatch can lead to repeated failures.

• Document and Monitor:
  Keep detailed notes of troubleshooting steps and monitor your system configuration to avoid future issues.

---

5. Best Practices for Future Troubleshooting

• Systematic Approach:
  Follow a clear sequence: log review → environment verification → compatibility check → corrective action → retest.

• Stay Updated:
  Regularly check official Jenkins documentation and Java support policies to keep your environment compliant.

• Backup Configurations:
  Always back up your Jenkins home directory and configuration files before making significant changes.

• Monitor Environment Changes:
  Periodically verify that your runtime environment (like Java version) is still compatible with Jenkins and its plugins.