[spring-sagan]스프링 홈페이지 따라하기

개요

이번 글의 목적은 "스프링 홈페이지를 로컬 환경에서 돌려보기" 입니다.

스프링은 공식 홈페이지(spring.io)를 스프링 프레임워크를 기반으로 구현하였고,

소스 코드는 Github 에서 확인해 볼 수 있습니다.

방문해보셨겠지만, 상당히 많은 문서를 제공하고 있습니다.

 

스프링 공식 홈페이지를 둘러보면 크게 4가지 토픽으로 정보를 제공하고 있습니다.

(프로젝트, 가이드, 블로그, 서비스)

이 중 프로젝트는 스프링이 제공하는 기능(프로젝트)에 대한 정보가 담겨있고,

가이드는 스프링 프레임워크를 어떻게 활용하는지 다양한 예시와 함께 제공되어 있습니다.

블로그는 스프링의 소식, 서비스는 스프링 비즈니스(?) 서비스와 관련된 정보가 포함되어 있습니다.

 

스프링 홈페이지 프로젝트의 이름은 sagan입니다.

sagan은 코스모스의 저자 칼 세이건의 이름에서 가져왔다고 합니다. (읽지는 못했지만,,. 이름은 많이 들어본 그 책!)

칼 세이건이 어떤 무엇인가를 잘 설명해내는 것처럼 스프링 홈페이지도 사람들이 원하는 것을

쉽게 알아낼 수 있도록 돕고 싶은 소망이 담겨있는 것 같습니다.

 

이 홈페이지를 (웹 서비스) 로컬 환경에서 작동시켜보는 것이 이번 글의 목표입니다.

 

결과 미리보기

성공적으로 수행, 동시에 제가 과정을 성공적으로 명세했다면,

다음과 같은 화면을 볼 수 있을 것입니다!

 

1. 홈페이지 화면

http://localhost:8080

2. 가이드 페이지 화면

http://localhost:8080/guides

 

과정

Spring sagan Project wiki 에는 로컬 환경에서 sagan 애플리케이션을 실행하는 과정이 자세하게 나와있습니다.

아래 과정은 이를 토대로 작성한 것임을 알립니다.

 

# 요약

1. JDK 1.8 설치

2. 소스 코드 가져오기

3. sagan 애플리케이션 실행하기

 

 

# 개발 환경 구축하기

 - JDK(Java Developement Kit) 1.8를 설치합니다.

 

스프링 sagan 프로젝트는 자바 1.8 버전과 호환됩니다.

저는 AdoptOpenJDK 1.8을 설치했습니다. 

JDK 설치 및 환경 변수 설정은 생략하겠습니다. (추후에 개별 포스팅 후 참조하기)

다음과 같은 화면을 확인하시면 됩니다.

$ javac -version
javac 1.8.XX

 

NOTE : 추가적으로 저는 처음 애플리케이션을 실행할 때에는 CLI(: 명령어 라인 인터페이스, Mac OS Terminal)을 통해서 진행했고, 

정상 작동을 확인한 뒤부터 현재 IDE 환경에서 작업중입니다.

Intellij Ultimate 2019.3 (학생 라이센스)를 사용중입니다.

포스팅은 CLI를 사용하여 진행합니다.

 

 

# 소스 코드 가져오기

 - git 설치 완료를 전제로 합니다.

 

타인의 Github 원격 저장소로부터 소스 코드를 가져오는 방법은 다양하게 있습니다.

그 중 해당 프로젝트를 fork하는 방법과 clone하는 방법이 있습니다. (Etc. zip 설치 및 압축 해제, svn checkout)

sagan 프로젝트는 fork 방식으로 시작하는 것을 권장합니다.

clone으로 시작할 경우, 원격 저장소는 sagan 프로젝트와 동일하게 설정되어 있고,

다양한 수정 활동에 제약이 발생할 수 있습니다. (특히나 버전 관리 시스템을 활용하고자 할 경우)

마음 편하게 이것저것 시도해보는 자유를 누리고자 하신다면,

마음 편하게 fork를 합시다. (클릭 몇 번 더 할 뿐입니다.)

 

1. Fork

Fork를 넘어가실 분은 바로 아래 Clone 으로 넘어가시면 됩니다.

1. sagan 프로젝트의 깃헙 페이지로 이동합니다.

2. 우측 상단의 fork를 클릭합니다.

3. 잠깐 기다립니다. (화면이 바뀌지 않을 경우 자신의 github 홈페이지로 이동)

4. 자신의 Github Repository 리스트에서 sagan 프로젝트를 선택합니다.

 

2. Clone

Fork를 하지 않으신 분은 ${GITHUB_USER_NAME} 에 `spring-io`를 입력하시면 됩니다. 

1. 명령어(터미널) 창 혹은 GUI 환경의 버전 관리 시스템을 실행합니다.

2. sagan 프로젝트 소스 코드를 관리할 파일 경로로 이동합니다.

3. 프로젝트를 clone 합니다.

$ git clone git@github.com:${GITHUB_USER_NAME}/sagan.git

 

NOTE : 아, 그리고 위 명령어는 공개키 설정이 되어있지 않은 컴퓨터(저의 경우 Mac)는 별도로 깃헙에 공개키 등록을 해두어야합니다.

이 방법도 어려우시다면 공식 홈페이지에 clone 버튼을 누르고 zip파일을 다운로드 하시거나,

아래 명령어를 이용하셔도 됩니다.

$ git clone https://github.com/${GITHUB_USER_NAME}/sagan.git

 

 

# sagan-site 애플리케이션 실행하기

 - gradle wrapper를 사용합니다.

 

sagan 프로젝트는 gradle 빌드 자동화 도구를 사용합니다.

프로젝트 빌드에 필요한 의존 관계, 라이브러리, 리소스, 버전, 등등 정말 다양한 설정들을 

도메인 특화 언어(DSL)로 명세하여 관리할 수 있도록 도와주는 도구입니다.

 

또한 Gradle Wrapper는 어떤 플랫폼에서든지 동일한 Gradle 작동을 보장합니다.

`gradlew` Wrapper를 사용하면, gradle 설치나 환경 설정 없이도 Gradle을 사용할 수 있습니다.

일정 버전 이상의 자바만 설치되어있으면 됩니다.

Window를 위한 bat 파일(.bat)과 UNIX 환경의 쉘 스크립트 파일을 제공합니다.

다만 Wrapper에 대한 수정을 위해서는 Gradle을 설치해야합니다.

 

NOTE : 마치 Python에서 pip 도구를 사용해서 필요한 이런저런 패키지를 requirements.txt로 관리하는 것과 비슷한 목적입니다.

다만 Gradle Wrapper는 빌드 전 필요한 의존 관계를 모두 해결합니다. Python은 파이프 명령어를 사용한 pip을 통해 개별적으로 설치해야합니다.

 

소스 코드를 clone 했다면 해당 위치에서 다음과 같은 명령어를 입력합니다.

$ cd sagan
$ ./gradlew sagan-site:bootRun  # Window의 경우 gradlew.bat 파일을 사용합니다.
...
2020-02-06 19:56:49.184  INFO 1518 --- [  restartedMain] sagan.SiteApplication                    : Started SiteApplication in 8.446 seconds (JVM running for 8.88)

 

그리고 `http://localhost:8080/`에 방문하면 스프링 공식 홈페이지와 같은 화면을 확인할 수 있습니다.

http://localhost:8080

 

 

하지만 GUIDES 페이지에 방문하면 아래 사진과 같이 HTTP 500 에러가 발생합니다.

http://localhost:8080/guides

당황하지 않고 spring-sagan wiki를 더 읽어본다면 곧바로 이유를 찾을 수 있습니다.

 

이유는 다음과 같습니다.

  1. guides에 대한 Rendering 결과가 없음.

 

해결 방법은 다음과 같습니다.

  1. Github Repository로부터 가이드의 Fetch & Download, Rendering을 수행하는 `sagan-renderer`를 실행합니다.

 

 

# sagan-renderer 애플리케이션 실행하기

 - sagan-site 애플리케이션이 실행된 상태로 진행합니다.

 

sagan-rednerer 애플리케이션은 sagan-site와 같은 방식으로 실행합니다.

$ ./gradlew sagan-renderer:bootRun # Window의 경우 gradlew.bat 파일을 사용합니다.
...
2020-02-06 21:18:55.212  INFO 1939 --- [  restartedMain] sagan.renderer.RendererApplication       : Started RendererApplication in 5.882 seconds (JVM running for 6.293)

 

 

# 확인하기

 - 결과를 확인합니다.

 

다시 한 번 `http://localhost:8080/guides`에 방문하면 약간의 지연 시간과 함께 성공적으로 가이드 페이지를 반환합니다.

http://localhost:8080/guides

 

spring-sagan 애플리케이션은 홈페이지 서비스를 담당하는 `sagan-site`와

Github spring-guides Organization Repositories 에서 적절한 명칭의 가이드를 가져와 렌더링하는 `sagan-renderer`가 있습니다.

 

사용자는 `http://localhost:8080/`을 통해 로컬 환경의 spring sagan 홈페이지에 접근할 수 있습니다.

이후 `http://localhost:8080/guides' 에 요청을 보내면 `sagan-site` 애플리케이션은 8081 포트로 리다이렉트를 수행합니다.

리다이렉트된 요청은 `sagan-renderer`에서 처리되어 결과를 반환하고 `sagan-site`는 해당 ResourceContent를 cache에 저장합니다.

그리고 사용자에게 보여주게됩니다.

 

 

결론

스프링은 이와 같은 구조로 최근에 변경한 것 같습니다. (2019년 5월 10일 커밋 참조)

기존에는 `sagan-indexer` 라는 애플리케이션을 통해 홈페이지의 다양한 리소스를 Indexing 했다면,

이후에는 `sagan-renderer` 애플리케이션을 활용하여 필요한 리소스를 동적으로 Rendering 하는 차이가 있는 것 같습니다.

Indexer는 자세히 보지 못했습니다....만 거의 추측...

 

위와 같이 기존의 스프링 공식 홈페이지와 똑같이 실행하는 것은 그렇게 어렵지 않았습니다.

너무나도 친절한 설명과 간단한 절차, 즉 빌드 자동화 덕분에 특별한 환경 설정이나 복잡한 명령어 없이도 따라할 수 있습니다.

이제 여기서 저만의 스프링 홈페이지를 만들어보고자 합니다.

가장 먼저 저의 Github Repository로부터 가이드를 렌더링하는 기능을 추가해보려고 합니다. 왜?

어떻게 해야할까요?

 

이들은 Wiki 페이지를 통해서 단순하게 properties에 몇 줄 넣으면 될 것이라고 말하지만,

사실 그렇지 않았습니다.

 

`sagan-site/src/main/resources/application.yml`를 수정하라고 하지만, 아무리 요리보고 조리봐도

가이드를 깃헙으로부터 가져오는 기능은 `sagan-renderer` 애플리케이션이 담당하는데

왜 경로가 저렇게 되는지 이해가 안갔습니다. (실제로 수정해도 안됩니다.)

 

그래서 `sagan-renderer` 애플리케이션을 살피기 시작했습니다.

그런데 이 애플리케이션 어딜 찾아봐도 guides에는 owner이라는 객체가 존재하지 않았습니다.

`sagan-renderer/src/main/java/sagan/renderer/RendererProperties.java`참조

 

여기저기 찾아보니 몇 달 전, 저와 같은 고민을 하시는 분도 있었습니다.

소스 코드를 여기저기 고치면서 원하는 바를 이룬 것 같았습니다.

 

하지만, 조금 더 잘 고쳐볼 수는 없을까? 고민해보고, 약간은 돌아가보기로 했습니다.

임시 방편보다는 재사용할 수 있는 코드를 만들어보고자!

 

우선 guides에 owner라는 개념을 추가하고 properties 설정을 통해 원하는 사용자의 깃헙 저장소로부터 

가이드를 fetch & download 하도록 수정했습니다. (wiki의 내용을 반영하여)

그런데 owner만 추가하고 나머지 기능은 모두 재사용하면서

새로운 요청에 대한 처리만 추가하는 방법이 떠오르지가 않았습니다.

경험이 부족한건지, 지식이 부족한건지, 둘 다인지...

 

한참을 고민하던 끝에, 이러다간 아무것도 못하겠구나 생각이 들었습니다.

그래서 일단 돌아가는 코드를 작성하는 것에 초점을 맞추었습니다.

 

그래, 일단 돌려나 보자

 

 

다음 글은 그렇게 "일단 돌아가는 내 홈페이지"를 만들어보고자 합니다.

 

 

참고 자료

1. Spring. 스프링 Sagan 프로젝트 wiki. https://github.com/spring-io/sagan/wiki

2. Spring. 스프링 가이드 프로젝트 wiki. https://github.com/spring-guides/getting-started-guides/wiki

3. AdoptOpenJDK. JDK 1.8 설치.  https://adoptopenjdk.net/

4. Git-SCM. 깃 소스 코드 관리 도구. https://git-scm.com/docs

5. Gradle. Gradle 빌드 자동화 도구. https://docs.gradle.org

6. Wikipedia. BAT 파일. https://ko.wikipedia.org/wiki/%EB%B0%B0%EC%B9%98_%ED%8C%8C%EC%9D%BC

7. Mozila. HTTP 500 Status Code. https://developer.mozilla.org/ko/docs/Web/HTTP/Status/500