[Nginx] Nginx + Jenkins 의 경로 문제 해결

1. 배경

 

Docker 환경에서 Jenkins를 컨테이너로 운영하면서 외부에서 Nginx를 통해 대시보드에 접근하고자 했습니다. Jenkins가 기본 루트(/)에서 동작하고 있었기 때문에, Nginx에서 /jenkins 경로로 요청을 전달하면 URL 경로 불일치 문제로 인해 404 에러 및 페이지 깨짐 현상이 발생했습니다.

 

2. 초기 설정과 문제점

(1) Nginx 설정

location /jenkins/ {
    proxy_pass http://jenkins:8080;  # Jenkins는 루트 컨텍스트에서 실행 중
    proxy_redirect default;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_max_temp_file_size 0;

    # 웹소켓 지원 관련 설정
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Upgrade $http_upgrade;

    client_max_body_size 10m;
    client_body_buffer_size 128k;
}

 

 위 설정만 존재할 때는 Jenkins와 Nginx 간에 컨텍스트가 달라 실제 요청 URL이 맞지 않아 문제가 발생했습니다. Jenkins는 루트(/)에서 동작하지만, Nginx에서는 /jenkins 경로로 요청을 전달합니다.

예를 들어, 클라이언트가 https://[도메인]/jenkins/job/test로 요청을 보내면, Nginx는 이 요청을 그대로 http://jenkins:8080/jenkins/job/test로 전달합니다.

그러나, Jenkins는 /jenkins/job/test 경로가 아닌 /job/test를 처리해야 하므로, 실제 URL이 맞지 않아 404 에러가 발생하게 됩니다.

 

3. 해결 방법

문제 해결을 위해 Jenkins의 실행 컨텍스트를 /jenkins로 변경하는 방식으로 접근했습니다.

(1) Jenkins 컨텍스트 변경 – Prefix 적용

Docker-Compose 파일에 환경 변수 JENKINS_OPTS=--prefix=/jenkins를 추가하여, Jenkins가 내부 URL에 /jenkins 접두사를 붙여 동작하도록 설정했습니다.

version: "3.8"

services:
  jenkins:
    image: myjenkins-docker:2.502
    container_name: jenkins
    environment:
      - JENKINS_OPTS=--prefix=/jenkins
    volumes:
      - /home/ubuntu/jenkins-data:/var/jenkins_home
      - /var/run/docker.sock:/var/run/docker.sock
    expose:
      - "8080"
    group_add:
      - "999"
    networks:
      - uptention_network

networks:
  uptention_network:
    external: true

 

 외부에서 https://[도메인]/jenkins/로 접근 시, Jenkins는 내부적으로 /jenkins로 시작하는 URL을 인식하므로, 위와 같이 전달된 요청이 올바르게 처리됩니다.

 

4. 결론

 Docker-Compose에 JENKINS_OPTS=--prefix=/jenkins 옵션을 추가하여, 외부에서 https://[도메인]/jenkins/로 접근 시 Jenkins가 내부적으로 /jenkins 접두사를 붙여 올바른 URL로 요청을 처리하도록 했습니다. 이 경험에서 웹 애플리케이션이 기본 루트(/)와 특정 접두사(/jenkins)로 동작할 때, 실제 요청 URL이 어떻게 매핑되는지 꼼꼼히 확인해야 한다는 점을 느꼈습니다. 읽어주셔서 감사합니다.