개발 환경 구축의 실전
Chapter 5. 개발 환경 구축
'이거... 다 해야 하는 거야?'
README 파일을 열었다.
"개발 환경 세팅" 섹션이 보인다.
Node 18.16.0 설치, npm install, Docker Desktop 실행, PostgreSQL 13 설치, Redis 구동, .env.local 파일 생성, 환경변수 20개 설정...
리스트가 스크롤을 내려도 끝이 안 보인다.
'이거... 다 해야 하는 거야?'
손이 떨린다. 뭐부터 시작해야 할지 막막하다. Python인지 Java인지도 모르겠고, Docker는 이름만 들어봤고, PostgreSQL은 SQL과 뭐가 다른지도 모르겠다.
'다른 신입들은 이거 다 알고 있나? 나만 모르는 건가?'
누구나 처음은 당황한다.. 필자도 처음엔 똑같았다 입사 3일 차. 팀장님이 "개발 환경 세팅 끝났어?"라고 물었을 때, 나는 시작도 못한 상태였다.
README를 열었을 때 내 반응은 "...뭐야 이게 다?"였다. Node 버전, Python 버전, Docker, MySQL, Redis, Kafka, Elasticsearch... 처음 보는 이름들이 줄줄이 나열되어 있었다.
일단 구글에 "Node 설치"를 검색했다. 공식 사이트에서 최신 버전을 다운로드했다. 20.11.1 버전이었다.
설치하고, README로 돌아와서 npm install 을 실행했다.
에러가 쏟아졌다.
Error: Node version mismatch Required: 18.16.0 Current: 20.11.1
'아... 버전이 달라서 안 되는 거였구나.'
Node를 지우고, 18.16.0을 다시 설치했다. 이번엔 됐다.
다음은 Docker였다. "Docker 설치"를 검색해서 Docker Desktop을 깔았다. 실행했다. README에 적힌 대로
docker-compose up 을 쳤다.
또 에러가 났다. 포트 충돌이었다. 내 노트북에 이미 MySQL이 깔려있어서 3306 포트를 쓰고 있었던 거다.
'MySQL을 꺼야 하나? 아니면 Docker 설정을 바꿔야 하나?'
1시간을 헤맸다. 결국 옆자리 선배한테 물었다.
"아, 그거? 로컬 MySQL 꺼. 회사에선 Docker로 통일해서 쓰거든."
선배는 5초 만에 답을 줬다. 나는 1시간 동안 구글링만 했다.
그날 깨달았다. 환경 세팅은 구글링으로 해결되지 않는다. 회사마다 설정이 다르고, 팀마다 쓰는 도구가 다르기 때문이다.
1단계: README부터 정독하라
대부분의 신입들은 README를 대충 훑고 바로 설치부터 시작한다. 스마트폰 메뉴얼을 정독하고 사용하지 않는 것처럼 그러다가 3시간 동안 에러만 보고, 결국 선배한테 물어봤더니 "README 2번 항목에 다 적혀있었는데요..."라는 말을 들었다.
부끄러웠다. 하지만 그 뒤로는 달라졌다. README를 처음부터 끝까지 천천히 읽기 시작했다.
README의 핵심 섹션들
대부분의 README는 비슷한 구조를 가지고 있다. 해당 문서를 읽을때 아래 사항을 유의하자.
설치해야 할 파일들이 제공된다면 제공된 파일로
"최신 버전"이 아닌 문서에서 요구하는 버전으로
설치 순서가 중요하다, 안내대로 1번부터 10번까지 순서대로 따라가자
에러와 해결 방법도 정독하자.
코드 블록(```)에 명령어가 다 있다면. 그 명령어대로 붙여넣자
실전 팁
README에 "Note:", "Warning:", "Important:" 같은 표시가 있으면 두 번 읽어라. 거기에 삽질 방지 팁이 있다.
2단계: 설치 순서 파악하기
README를 다 읽었다. 이제 뭘 설치할지는 알겠다. 근데 어떤 순서로 설치해야 할까?
회사마다 다르지만, 일반적인 패턴이 있다.
언어 런타임이 가장 먼저다
프로그래밍 언어 실행 환경을 먼저 깔아야 한다.
Python이면 Python
Node.js면 Node.js
Java면 JDK
버전이 매우 중요하다. README에 "Node 18.16.0"이라고 적혀있으면, 20 버전 깔았다고 되는 게 아니다.
버전 관리 도구를 쓰면 편하다
회사에서는 프로젝트마다 다른 버전을 써야 할 때가 많다.
Node.js -> nvm (Node Version Manager)
Python -> pyenv
Java -> jenv
에피소드
README에 어떤 걸 쓰라고 적혀있는걸 무시하고, 필자도 처음에는 멋대로 프로그램을 설치했다. 결국 설치된 프로그램들이 충돌해서 다시 지우는데에만 하루가 걸렸던 적이 있다. 입사하자마자 일명 삽질로 하루를 날려 먹은 것이다. README를 끝까지 안 읽어서 생긴 일이었다.
3단계: 환경변수와 설정 파일
설치가 거의 끝나간다. 이제 중요한 단계가 남았다.
README를 보면 이런 문구가 있다.
"설정 파일을 생성하고 필요한 값을 입력하세요"
'설정 파일? 뭘 입력하라는 거지?'
대부분의 프로젝트는 비밀 정보를 별도 파일로 관리한다. 데이터베이스 비밀번호, API 키, 서버 주소 같은 것들 말이다.
이런 정보를 코드에 직접 쓰면? GitHub에 올라가서 전 세계에 공개된다. 그래서 별도 파일로 빼두는 거다.
어떻게 해야 할까?
보통 README에 이렇게 적혀있다.
"example 파일을 복사해서 실제 파일을 만드세요"
예시 파일을 찾는다. 프로젝트 폴더 어딘가에 "example", "sample", "template" 같은 단어가 들어간 파일이 있을 거다.
그걸 복사해서 파일명을 바꾼다. 그리고 안에 있는 빈칸이나 물음표를 실제 값으로 채워 넣는다.
값은 어디서 가져오나?
여기서 막힌다. 이 비밀번호를 어디서 받아야 하는지 모르겠다.
답은 간단하다. 선배한테 물어봐라.
"개발 환경 설정에 필요한 DB 비밀번호는 어디서 받을 수 있나요?"
부끄러운 질문이 아니다. 모든 신입이 묻는다.
팀마다 관리하는 곳이 다르다. 메신저 고정 메시지, 사내 위키, 비밀번호 관리 도구, 또는 직접 전달해주기도 한다.
에피소드
두 번째 회사 입사 첫날. 설정 파일의 API 키를 어디서 받아야 할지 몰라서 30분 동안 사내 위키를 뒤졌다. "API", "설정", "환경변수" 키워드로 검색해봤지만 찾을 수 없었다.
결국 옆자리 선배한테 물었다.
"API 키는 팀장님한테 직접 받으셔야 해요. 보안상 문서화 안 해놔서요."
'아... 그럼 그렇다고 README에 적어두지...'
이런 일이 흔하다. README가 완벽하지 않을 때도 많다. 오래전에 작성돼서 업데이트가 안 된 경우도 있고, 암묵적으로 다들 아는 거라서 안 적어둔 경우도 있다.
모르면 바로 물어보는 게 답이다. 혼자 30분 헤매는 것보다 5초 만에 답을 듣는 게 낫다.
실전 팁
받은 비밀번호나 설정값은 따로 메모해두자. 나중에 노트북을 바꾸거나 재설정할 때 또 써먹을 수 있다. 물론 회사 보안 정책을 따라야 한다.
4단계: 패키지 설치 명령어 실행
이제 진짜 설치다. README에 적힌 명령어를 실행한다.
터미널을 열고, 프로젝트 폴더로 이동한다. 그리고 명령어를 입력한다.
화면에 수많은 텍스트가 스크롤된다. 패키지들이 설치되고 있다.
3분... 5분... 10분...
'이거 맞게 되고 있는 건가? 너무 오래 걸리는데...'
걱정하지 마라. 처음 설치는 시간이 오래 걸린다. 프로젝트가 크면 10분, 20분도 걸린다.
커피 한 잔 타 와도 된다. 화장실 다녀와도 된다.
설치 중 에러가 난다면?
설치가 중간에 멈추고 빨간 글씨 에러 메시지가 뜬다.
'이런... 뭐가 잘못된 거지?'
당황하지 마라. 환경 설정에서 에러 안 나는 사람은 없다.
흔한 에러들
네트워크 에러: 회사 방화벽 때문에 특정 사이트 접속이 막혔을 수 있다. 선배한테 물어보자.
권한 에러: 관리자 권한이 필요하다는 메시지. 하지만 함부로 관리자 권한을 쓰지 말고, 선배한테 먼저 물어보는 게 안전하다.
버전 충돌: 이미 깔린 프로그램과 버전이 안 맞는다는 거다. README를 다시 확인해서 정확한 버전인지 체크하자.
에러 메시지는 끝까지 읽자 에러가 나면 화면에 수십 줄의 빨간 글씨가 쏟아진다. 겁먹지 마라
중요한 건 맨 마지막 줄이다. 거기에 진짜 에러 원인이 적혀있다.
나는 처음엔 에러 메시지가 너무 많아서 스크롤을 위로 올려서 처음부터 읽으려고 했다. 그게 아니다. 맨 아래로 내려서 마지막 줄부터 읽어야 한다.
5단계: 막히면 15분 안에 물어봐라
환경 설정은 삽질의 연속이다.
README대로 했는데 안 된다. 구글에 검색해봐도 비슷한 사례는 있는데 정확히 같은 건 없다. 이것저것 시도해봐도 계속 에러만 난다.
1시간... 2시간... 시간이 흘러간다.
'이거 혼자 해결 못 하면 무능한 건가? 팀장님한테 뭐라고 보고하지?'
불안해진다.
15분 룰
15분 고민해도 안 되면 바로 물어봐라.
"README 대로 설치 명령어를 실행했는데 이런 에러가 나요."
이게 부끄러운 게 아니다.
환경 설정은 회사마다, 팀마다 고유한 설정이 있다. 구글에도 답이 없고, ChatGPT도 모를 수 있다.
선배들도 다 겪었던 문제들이다. 물어보면 "아, 그거?"하고 5초 만에 답해준다.
어떻게 물어볼까?
나쁜 질문: "환경 설정이 안 돼요."
뭐가 안 되는지 알 수 없다.
좋은 질문: "README 3단계에서 설치 명령어 실행했는데 '권한 에러'가 나요. (스크린샷 첨부) 관리자 권한으로 실행해도 되나요?"
어느 단계에서, 무엇을 했고, 어떤 결과가 나왔는지 명확하다. 그리고 내가 어떻게 하려고 하는지도 물어본다.
에피소드
첫 회사에서 환경 설정하는 데 이틀이 걸렸다. 혼자 구글링만 하다가 시간을 다 날렸다.
두 번째 회사에서는 달랐다. 막히는 순간 바로 선배한테 물었다. 5분 만에 해결됐다.
선배가 그러더라.
"환경 설정은 원래 이래요. 회사마다 설정이 다 달라서 구글링으로 안 풀려요. 막히면 바로 물어보세요. 저도 신입 때 이틀 동안 혼자 삽질했거든요."
그 말을 듣고 안심이 됐다. 나만 모르는 게 아니었구나.
실전 팁
실행한 명령어, 에러 메시지, 스크린샷을 함께 보내면 선배가 답하기 쉽다.
"구글에서 이렇게 찾아봤는데 안 됐어요"까지 말하면 더 좋다. 노력은 했다는 걸 보여주니까.
질문할 때 "죄송한데요..."로 시작하지 마라. 환경 설정은 신입의 통과의례다. 사과할 일이 아니다.
6단계: 첫 실행 테스트
드디어 모든 설치가 끝났다.
README에 "실행 방법" 또는 "테스트" 섹션이 있다. 거기 적힌 명령어를 입력한다.
터미널에 뭔가 뜬다.
"서버가 시작되었습니다" 같은 메시지가 보인다.
'오... 됐나?'
README에 적힌 주소로 브라우저를 연다. 보통 localhost 뒤에 숫자가 붙은 주소다.
화면이 뜬다!
회사 서비스의 로그인 페이지나 메인 화면이 보인다.
'진짜... 됐네!'
가슴이 두근거린다. 드디어 성공했다.
안 뜬다면?
브라우저에 에러 페이지가 뜬다. 또는 아무것도 안 뜬다. 다시 터미널을 확인한다. 에러 메시지가 있나?
있다면 선배한테 물어본다. 없는데도 안 되면? 역시 선배한테 물어본다.
에피소드
세 번째 회사 입사 첫날. 모든 설치를 끝내고 서버를 실행했다. 터미널에는 "서버 실행 중"이라고 떴는데, 브라우저에서는 아무것도 안 떴다.
10분 동안 이것저것 시도해봤다. 브라우저를 바꿔보고, 주소를 다시 입력해보고, 터미널을 껐다 켰다 해봤다.
선배한테 물었더니,
"아, 그거 데이터베이스 마이그레이션 안 돌리셨죠? README 5단계에 있어요."
README를 다시 보니 정말 있었다. 5단계를 건너뛰었던 거다.
마이그레이션 명령어를 실행했더니 바로 됐다.
교훈은 README는 순서대로 하나도 빠뜨리지 말고 따라가야 한다.
7단계: 테스트로 확인
화면이 떴다고 끝이 아니다. 제대로 작동하는지 확인해봐야 한다.
간단한 동작을 테스트해본다. 로그인을 해보거나, 버튼을 눌러보거나, 데이터를 조회해본다. 잘 되면 성공이다!
그리고 한 번 더 확인한다. 서버를 끄고 다시 켜본다.
두 번째도 잘 되면 진짜 성공이다.
왜 두 번 확인하냐고? 첫 번째는 운 좋게 된 거일 수도 있으니까. 두 번째도 되면 제대로 설정된 거다.
환경 설정 완료!
브라우저를 열고 로컬서버 에 접속한다.
화면이 뜬다. 회사 서비스의 로그인 페이지다.
'됐다!'
가슴이 두근거린다. 3일 동안 씨름한 환경 세팅이 드디어 끝났다.
옆자리 선배가 웃으며 말한다.
"오, 됐어? 고생했다. 이제 진짜 개발 시작이야."
환경 세팅은 시작일 뿐이다. 하지만 이 시작을 넘었다는 게 중요하다.
이제 코드를 읽을 수 있다. 수정할 수 있다. 테스트할 수 있다.
드디어 개발자로서 첫 실행화면을 띄웠다.