Portless로 Git worktree마다 개발 서버 주소 구분하기

서로 다른 브랜치의 화면을 비교하려고 개발 서버를 두 개 실행하면, 두 번째 서버가 포트를 바꾸거나 실행을 멈출 수 있습니다. 포트가 바뀐 뒤 이전 브라우저 탭에서 새 변경을 확인하면 다른 브랜치의 화면을 보고도 구현이 반영되지 않았다고 판단할 수 있습니다.

Git worktree는 한 저장소의 서로 다른 브랜치를 별도 작업 디렉터리에서 열도록 하는 기능입니다. 파일을 나눠 작업할 수 있지만 각 디렉터리의 개발 서버가 같은 포트를 요청하는 문제까지 해결하지는 않습니다. Portless는 앱 이름을 포함한 로컬 주소를 제공하고, 그 주소의 요청을 실제 개발 서버로 전달합니다.

브라우저가 보는 주소와 서버가 쓰는 포트

포트는 같은 컴퓨터에서 실행 중인 서버들을 구분하는 번호입니다. Portless를 사용해도 앱은 포트에서 요청을 받습니다. 브라우저에는 myapp.localhost 같은 이름을 보여주고, 중간의 프록시가 그 이름을 앱의 포트에 연결합니다. 프록시는 요청을 받아 대상 서버에 전달하는 서버입니다.

예를 들어 기본 작업 디렉터리의 앱이 4101번 포트, fix-ui 브랜치의 앱이 4102번 포트를 사용한다고 가정하겠습니다. 브라우저에서 기본 앱 주소를 열면 프록시가 4101번으로 전달하고, 브랜치 주소를 열면 4102번으로 전달합니다. 이 포트 값은 설명을 위한 예시입니다. 실제 값은 실행 시 확인합니다.

각 호스트 이름과 개발 서버의 연결을 나타낸 예시입니다. 서버를 다시 실행하면서 내부 포트가 바뀌더라도 이름으로 접근할 수 있도록 프록시의 등록 정보를 갱신합니다.

브라우저 탭이나 테스트 설정에 이 주소를 쓰면 실행 때마다 포트 번호를 고쳐 적는 일을 줄일 수 있습니다. 다만 주소가 안정적이라는 것과 대상 서버가 정상이라는 것은 별개입니다. 종료된 서버나 잘못된 경로를 가리키는 등록 정보는 요청 실패로 이어질 수 있습니다.

연결된 worktree에 붙는 브랜치 이름

Portless의 worktree 안내에 따르면 portless run은 연결된 worktree를 감지해 브랜치 이름을 주소 앞에 붙입니다. 기본 작업 디렉터리는 기본 이름을 사용합니다. 같은 기본 이름을 지정하면 어느 앱의 작업 브랜치인지 주소에서 구분할 수 있습니다.

Portless가 설치돼 있고 각 작업 디렉터리에서 Next.js를 실행할 수 있다면 다음과 같이 사용할 수 있습니다.

# 기본 작업 디렉터리에서 실행
portless run --name myapp next dev
# https://myapp.localhost

# fix-ui 브랜치의 연결된 worktree에서 실행
portless run --name myapp next dev
# https://fix-ui.myapp.localhost

두 명령은 각각의 작업 디렉터리에서 실행합니다. 두 번째 명령을 기본 디렉터리에서 다시 실행한다고 fix-ui 주소가 생기는 것은 아닙니다. 브랜치 이름이 fix-ui이고 해당 디렉터리가 연결된 worktree라는 조건이 필요합니다.

앱 이름을 생략하면 도구가 이름을 추론합니다. 팀의 브라우저 테스트나 실행 안내에서 같은 이름을 계속 사용해야 한다면 명시한 이름과 실제로 출력된 URL을 대조합니다. 슬래시가 들어간 브랜치 이름처럼 호스트 이름으로 바꿔야 하는 경우에는 주소를 추측하지 말고 실행 결과를 확인합니다.

여러 앱의 주소를 한 디렉터리에서 구분하기

worktree를 나누는 것과 한 저장소 안의 앱을 나누는 것은 서로 다른 구분입니다. 하나의 작업 디렉터리에도 웹 화면, 관리자 화면, 문서 사이트가 함께 있을 수 있습니다. 이때는 앱마다 이름을 붙여 어느 서버로 연결되는지 나타낼 수 있습니다.

Portless 데모는 acme 프로젝트의 admin, docs, web에 서로 다른 주소를 표시합니다. 이 이미지는 앱 이름을 나누는 예시이며, worktree 브랜치 접두사를 보여주는 화면은 아닙니다.

이 구분을 실행 기록에도 남깁니다. 화면을 확인한 주소, 대상 worktree, 서버를 실행한 디렉터리가 함께 있어야 다른 사람이 같은 화면을 열 수 있습니다. 테스트가 실패했을 때도 화면 구현 오류인지 다른 서버에 접속한 것인지 구분할 수 있습니다.

HTTPS와 별도로 확인할 개발 환경

공식 안내의 기본 실행은 HTTPS를 사용합니다. 첫 실행에는 로컬 인증서와 신뢰 설정이 관련될 수 있습니다. 로컬 인증 기관은 개발용 인증서를 발급하는 주체이며, 브라우저가 그 인증서를 신뢰해야 경고 없이 연결할 수 있습니다. 필요한 권한과 절차는 운영체제 및 실행 환경에 따라 확인합니다.

앱이 Portless가 전달한 포트 설정을 실제로 사용하는지도 확인해야 합니다. 공식 안내에는 지원 프레임워크의 포트 인자를 조정하는 동작이 있지만, 복합 실행 명령이나 별도 서버 코드까지 모두 같은 방식으로 처리되는 것은 아닙니다. 연결이 실패하면 출력된 주소와 앱의 실제 수신 포트부터 대조합니다.

이름이 다른 주소들은 브라우저에서 서로 다른 출처로 취급될 수 있습니다. 출처는 프로토콜, 호스트, 포트의 조합입니다. 로컬 저장소나 로그인 콜백, API의 허용 출처 설정을 고정된 이전 주소에 맞췄다면 새 주소로 테스트할 때도 동작하는지 살펴봅니다.

주소를 나눠도 공유될 수 있는 데이터

두 worktree의 개발 서버 주소가 달라도 같은 데이터베이스에 연결하면 같은 데이터를 읽고 바꿀 수 있습니다. 환경 파일의 API 주소, 파일 업로드 경로, 외부 서비스의 테스트 계정도 공유될 수 있습니다. Portless의 주소 구분은 이 자원들을 별도로 생성하는 기능이 아닙니다.

병렬 작업을 시작하기 전에 어떤 데이터를 공유해도 되는지 정합니다. 한 브랜치에서 테스트 데이터를 지웠을 때 다른 브랜치의 테스트가 실패한다면 주소 구분만으로 해결할 수 없습니다. 별도의 데이터베이스나 데이터 구분 규칙이 필요할 수 있습니다.

두 주소를 열고 각 worktree에만 있는 작은 화면 변경이 각각 표시되는지 확인합니다. 이어서 브라우저 테스트가 같은 주소를 사용하도록 맞추고, 서버를 다시 실행해도 연결이 유지되는지 확인합니다. 이 검증을 거치면 변경한 브랜치와 확인한 화면을 연결해 기록할 수 있습니다.