클로드 코드로 만든 웹사이트, 깃허브 페이지에 올리고 도메인 연결하는 전체 과정

클로드 코드로 웹사이트를 만들면 내 컴퓨터에 index.html 파일 하나가 생깁니다. 더블클릭하면 잘 열립니다. 그런데 그 화면을 남한테 보여줄 방법이 없습니다. 파일이 내 컴퓨터 안에만 있으니까요.

이 글은 그 파일을 인터넷 주소가 있는 진짜 웹사이트로 만드는 전체 과정입니다. 깃허브 페이지에 올리는 데 20분, 도메인을 연결하는 데 10분, DNS가 퍼지길 기다리는 데 최대 24시간 걸립니다. 서버 비용은 0원이고, 도메인 값만 1년에 만 원 남짓 듭니다.

이 글은 방법만 나열하지 않습니다. 각 단계마다 왜 그래야 하는지를 같이 적었습니다. 이유를 알면 안내문에 없는 상황이 닥쳤을 때도 스스로 판단할 수 있습니다.

먼저: 웹사이트가 뜨는 원리 3줄

이걸 알고 시작하면 뒤의 모든 설정이 왜 필요한지 자동으로 이해됩니다.

1. 사람이 주소창에 focusaiedu.com을 칩니다
2. DNS가 그 이름을 IP 주소로 바꿔줍니다. 전화번호부와 같은 역할입니다
3. 그 서버가 해당 폴더에서 파일을 찾아 브라우저에 보냅니다

이 글에서 하는 일은 딱 두 가지입니다. 3번의 서버 자리에 깃허브를 앉히고, 2번의 전화번호부에 내 도메인을 등록하는 것. 나머지는 다 부속 작업입니다.

준비물 3가지

• 깃허브 계정 (무료)
• 클로드 코드로 만든 index.html
• 도메인 (선택. 가비아, 후이즈, 카페24 등 어디서 사도 됩니다)

도메인이 없어도 됩니다. username.github.io/저장소이름 형태의 주소가 자동으로 생깁니다. 도메인은 나중에 붙여도 되고, 붙이면 주소가 focusaiedu.com처럼 바뀝니다.

전체 흐름은 5단계입니다

1. 파일 준비 (파일 이름과 폴더 구조 지키기)
2. 깃허브 저장소 만들고 파일 올리기
3. 깃허브 페이지 켜기
4. 도메인 연결 (DNS 설정)
5. HTTPS 켜기

한 번 세팅하고 나면 그다음부터 수정은 명령어 3줄입니다.

01 파일을 올리기 전에 확인할 3가지

여기서 안 맞추면 뒤에서 반드시 막힙니다.

파일 이름은 반드시 index.html

먼저 왜인지부터 보겠습니다.

주소창에 focusaiedu.com만 치면, 사실 우리는 서버에게 파일 이름을 하나도 알려주지 않은 겁니다. 폴더 주소만 준 거예요. 컴퓨터에서 폴더를 더블클릭하면 그 안의 파일 목록이 나오죠. 서버도 원래는 그럴 수 있습니다. 그런데 웹사이트에서 폴더 안 파일 목록이 그대로 노출되면 곤란합니다. 남의 사이트 파일을 전부 뒤져볼 수 있게 되니까요.

그래서 초기 웹 서버들이 규칙 하나를 만들었습니다. 파일 이름 없이 폴더 주소만 들어오면, 그 폴더 안의 index.html을 대신 보여준다. index는 책의 색인, 즉 그 폴더의 대표 페이지라는 뜻입니다. 이 규칙이 30년 넘게 굳어져서 지금도 거의 모든 웹 서버의 기본값입니다.

깃허브 페이지도 이 규칙을 따릅니다. 그런데 일반 서버는 설정 파일을 고쳐서 "home.html을 대표 페이지로 써라"라고 바꿀 수 있는 반면, 깃허브 페이지는 서버 설정에 손댈 수 없습니다. 무료 정적 호스팅이라 사용자에게 서버 설정 권한을 주지 않습니다.

이 규칙은 하위 페이지에도 똑같이 적용됩니다. 뒤의 404 항목에서 다시 나옵니다.

이미지와 폰트는 파일 안에 심는 게 안전합니다

이것도 이유가 명확합니다. 두 가지 때문입니다.

첫째, 경로 기준이 바뀝니다. 내 컴퓨터에서 파일을 더블클릭해 열면 브라우저 주소창이 file:///Users/…로 시작합니다. 배포하면 https://로 시작하죠. 이 둘은 상대 경로를 푸는 방식이 미묘하게 다릅니다. 로컬에서 멀쩡하던 이미지 경로가 배포하면 깨지는 이유가 대부분 이겁니다.

둘째, 대소문자입니다. 이게 진짜 함정입니다. 맥과 윈도우는 파일 이름의 대소문자를 구분하지 않습니다. Logo.png와 logo.png를 같은 파일로 취급해요. 그런데 깃허브 페이지 서버는 리눅스라 대소문자를 엄격하게 구분합니다. HTML에는 logo.png라고 썼는데 실제 파일이 Logo.png면, 내 컴퓨터에서는 잘 나오고 배포하면 안 나옵니다. 원인을 찾기가 대단히 어렵습니다.

파일이 하나면 이 두 문제가 아예 발생하지 않습니다. 참조할 외부 파일이 없으니까요. 처음 배포할 때는 클로드 코드에게 이렇게 요청하세요.

사이트가 커지면 그때 분리하면 됩니다. 그때는 이미 원리를 알고 있으니 안 무섭습니다.

폴더 이름에 띄어쓰기를 쓰지 마세요

터미널은 띄어쓰기를 "여기서 다음 항목이 시작된다"는 신호로 읽습니다. 사람 눈에 my site는 폴더 이름 하나지만, 터미널은 my와 site라는 별개의 항목 두 개로 읽습니다. 그래서 cd my site라고 치면 my라는 폴더로 가려다 실패합니다.

따옴표로 감싸면 되긴 하지만, 매번 그러느니 처음부터 안 만드는 게 낫습니다. my-site처럼 하이픈으로 연결하세요.

02 깃허브에 올리기

저장소 만들기

github.com에서 New repository를 누릅니다. 이름은 영문 소문자와 하이픈으로 짓습니다.

반드시 Public으로 만드세요. 무료 계정은 공개 저장소에서만 깃허브 페이지를 쓸 수 있습니다. 왜 그럴까요. 깃허브 페이지는 원래 오픈소스 프로젝트의 문서 사이트를 무료로 호스팅해주려고 만든 기능입니다. 공개를 전제로 무료인 서비스라, 비공개로 쓰려면 유료 플랜을 사라는 구조입니다.

Add a README 같은 체크박스는 전부 해제하고 만듭니다. 비어 있는 저장소가 더 편합니다.

터미널에서 올리기

만든 저장소 화면에 나오는 주소를 복사해두고, 터미널에서 내 사이트 폴더로 이동합니다.

cd ~/my-site
git init
git add .
git commit -m "first deploy"
git branch -M main
git remote add origin https://github.com/내아이디/저장소이름.git
git push -u origin main

명령어가 6줄이라 복잡해 보이는데, 하는 일은 4가지뿐입니다.

• git init — 이 폴더를 깃이 관리하는 폴더로 지정
• git add + git commit — 지금 상태를 저장점으로 찍기. 내 컴퓨터 안에서만 일어나는 일입니다
• git remote add — 이 폴더가 어느 깃허브 저장소와 짝인지 등록
• git push — 그 저장소로 실제로 보내기

commit과 push가 왜 나뉘어 있는지 궁금하실 텐데, 이게 깃의 핵심입니다. 커밋은 내 컴퓨터에 찍는 저장점이라 인터넷 없이도 됩니다. 여러 번 커밋하고 한 번에 푸시할 수도 있습니다. 저장과 공개를 분리해둔 덕에, 다 완성된 상태만 골라서 올릴 수 있습니다.

이 과정 전체를 클로드 코드에게 시켜도 됩니다. "이 폴더를 깃허브 저장소 ○○에 올려줘"라고 하면 명령어를 대신 실행합니다. 다만 무슨 일이 일어나는지는 알고 시키는 게 좋습니다. 안 그러면 나중에 꼬였을 때 어디를 봐야 할지 모릅니다.

03 깃허브 페이지 켜기

저장소 화면에서 Settings › Pages로 들어갑니다.

• Source — Deploy from a branch
• Branch — main
• 폴더 — / (root)
• Save

여기서 Branch를 고르라는 이유는, 하나의 저장소 안에 여러 갈래의 작업본이 있을 수 있기 때문입니다. 어느 갈래를 세상에 보여줄지 지정하는 겁니다. 갈래를 나눠 쓰지 않는다면 main 하나뿐이니 그냥 main을 고르면 됩니다.

1~2분 뒤 화면 위쪽에 주소가 뜹니다. https://내아이디.github.io/저장소이름/ 형태입니다. 눌러서 사이트가 뜨면 성공입니다.

바로 안 뜨면 저장소 상단의 Actions 탭을 보세요. 초록 체크면 배포 완료, 빨간 X면 빌드 실패입니다.

왜 배포에 1~2분이 걸리나요

푸시한 순간 파일이 바로 서비스되는 게 아니라, 깃허브가 파일을 받아서 검사하고 변환한 뒤 전 세계 배포망에 복사하는 과정을 거칩니다. 이 과정이 Actions 탭에 기록됩니다. 그래서 "푸시는 성공했는데 사이트는 그대로"인 구간이 잠깐 존재합니다. 정상입니다.

.nojekyll 파일이 필요한 경우

깃허브 페이지는 태생이 Jekyll이라는 블로그 엔진용 서비스였습니다. 그래서 지금도 파일을 받으면 기본적으로 Jekyll을 한 번 돌립니다. 마크다운을 HTML로 바꾸고, 템플릿을 조립하는 과정입니다.

문제는 우리가 이미 완성된 HTML을 올렸다는 겁니다. Jekyll 입장에서는 굳이 할 일이 없는데도 검사를 하고, 그러다 두 가지 상황에서 사고를 칩니다.

• 밑줄로 시작하는 폴더(_assets 같은)를 내부용으로 착각해서 배포에서 빼버립니다
• HTML 안에 중괄호 두 개가 있으면 자기 템플릿 문법으로 읽고 에러를 냅니다. 자바스크립트 코드에 이 모양이 흔히 등장합니다

둘 다 원인을 짐작하기 어려운 형태로 터집니다. 폴더 맨 위에 .nojekyll이라는 빈 파일을 하나 두면 이 과정을 통째로 건너뜁니다.

touch .nojekyll
git add .nojekyll
git commit -m "add nojekyll"
git push

이유 없이 배포가 실패한다면 이걸 먼저 해보세요.

04 도메인 연결하기

여기가 제일 헷갈리는 구간인데, 실제로는 설정 두 군데를 맞추는 게 전부입니다. 깃허브 쪽에 "나 이 도메인 쓸 거야"라고 알리고, 도메인 회사 쪽에 "이 도메인은 깃허브로 보내"라고 알립니다.

왜 양쪽에 다 알려야 하나요

이게 이 단계의 핵심 원리입니다.

깃허브 페이지의 서버 IP는 전 세계 사용자가 공유합니다. 아래에 나올 A 레코드 4개는 내 전용 주소가 아니라, 깃허브 페이지를 쓰는 수백만 개 사이트가 똑같이 쓰는 주소입니다.

그러면 그 서버는 접속이 들어왔을 때 누구의 사이트를 보여줘야 할지 어떻게 알까요. 브라우저가 보내는 요청 안에 "내가 치고 들어온 도메인 이름"이 같이 담겨 있습니다. 서버는 그 이름을 보고 "focusaiedu.com을 등록한 저장소가 어디더라" 하고 찾아서 그 저장소의 파일을 내보냅니다.

순서를 지키세요: 깃허브 먼저, DNS 나중

이 순서에도 이유가 있습니다. DNS만 먼저 깃허브로 돌려놓고 깃허브에 도메인 등록을 안 해두면, 그 도메인은 "깃허브를 가리키는데 주인이 없는 상태"가 됩니다. 이때 다른 사람이 자기 저장소에 그 도메인을 먼저 등록해버리면, 내 도메인으로 남의 사이트가 뜹니다. 실제로 자주 일어나는 공격 방식이라 깃허브 공식 문서도 이 순서를 권합니다.

Settings › Pages › Custom domain 칸에 도메인을 입력하고 Save를 누릅니다. 저장소에 CNAME이라는 파일이 자동으로 하나 생깁니다. 지우면 안 됩니다. 서버가 "이 저장소는 이 도메인 담당"이라고 판단하는 근거가 바로 이 파일입니다.

도메인 회사에서 DNS 설정 (가비아 기준)

My가비아 › 서비스 관리 › 도메인 › DNS 관리 툴 › DNS 설정으로 들어갑니다.

apex 도메인(www 없는 focusaiedu.com)을 쓴다면 A 레코드 4개를 추가합니다.

왜 4개나 넣나요

한 개만 넣으면 그 서버가 점검이나 장애로 잠깐 멈출 때 내 사이트도 같이 멈춥니다. 4개를 넣어두면 브라우저가 하나에 실패했을 때 다음 것으로 넘어갑니다. 4개를 다 넣는 건 선택이 아니라 안정성의 조건입니다.

왜 apex 도메인은 CNAME이 아니라 A 레코드인가요

www.focusaiedu.com은 CNAME으로 처리하는데 focusaiedu.com은 A 레코드를 써야 합니다. 왜 다르냐면, DNS 규칙상 CNAME은 "이 이름에 대한 모든 질문을 저쪽으로 넘겨라"라는 뜻이라 다른 정보와 공존할 수 없기 때문입니다.

그런데 도메인의 최상단(apex)에는 이미 필수 정보들이 붙어 있습니다. 이 도메인을 어느 네임서버가 관리하는지, 메일은 어디로 보낼지 같은 것들이요. 여기에 CNAME을 걸면 그 정보들과 충돌합니다. 그래서 apex에는 IP를 직접 적는 A 레코드를 씁니다.

이건 깃허브의 제약이 아니라 DNS 자체의 규칙이라, 어떤 호스팅을 쓰든 똑같습니다. 알아두면 나중에 다른 서비스를 붙일 때도 그대로 쓰입니다.

www도 함께 쓰려면

CNAME을 하나 더 추가합니다.

값 끝의 마침표는 가비아가 요구하는 경우가 있습니다. 입력창 안내를 따르세요.

www 쪽을 CNAME으로 걸어두면 좋은 점이 하나 있습니다. 깃허브가 나중에 서버 IP를 바꿔도 www 주소는 영향을 안 받습니다. 이름으로 따라가니까요. IP를 직접 적어둔 apex만 손보면 됩니다.

IPv6까지 챙기고 싶다면 AAAA 레코드 4개(2606:50c0:8000::153 ~ 2606:50c0:8003::153)를 추가로 넣을 수 있습니다. 필수는 아닙니다.

왜 24시간이나 기다리나요

DNS는 전 세계 통신사와 서버들이 답을 각자 복사해두고 재사용하는 구조입니다. 매번 원본에 물어보면 인터넷이 마비되니까요. 이 복사본에는 유효기간이 붙어 있고, 그게 만료돼야 새 정보를 다시 가져옵니다.

그래서 내가 방금 바꿨어도, 이미 옛날 답을 복사해둔 곳들은 유효기간이 끝날 때까지 옛날 답을 씁니다. 보통 10분에서 1시간, 늦으면 24시간입니다. 5분 만에 안 된다고 설정을 다시 건드리면 오히려 처음부터 다시 세는 셈이라 더 늦어집니다. 한 시간 뒤에 다시 보세요.

05 HTTPS 켜기

DNS가 연결되면 Settings › Pages 화면의 Enforce HTTPS 체크박스가 활성화됩니다. 체크하세요. 주소 앞에 자물쇠가 붙고, http로 들어온 사람도 https로 자동 전환됩니다.

왜 체크박스가 회색으로 막혀 있나요

HTTPS를 켜려면 인증서가 필요하고, 인증서는 "이 도메인이 정말 이 사람 것"이라는 확인을 거쳐야 발급됩니다. 확인 방법은 간단합니다. 그 도메인에 실제로 접속해서 깃허브 서버가 응답하는지 보는 겁니다.

그러니까 DNS가 아직 안 퍼졌으면 확인 자체가 불가능하고, 그래서 체크박스가 잠겨 있습니다. 순서가 강제되는 겁니다. 보통 DNS 연결 후 몇십 분 안에 풀립니다.

하루가 지나도 안 풀리면 Custom domain 칸을 비우고 Save한 다음, 다시 입력하고 Save하세요. 인증서 발급이 재시도됩니다.

자주 막히는 지점 5가지

사이트는 뜨는데 디자인이 다 깨져 보입니다

CSS 파일을 못 찾은 겁니다. 앞에서 설명한 경로 기준 차이나 대소문자 문제일 확률이 높습니다. 브라우저에서 F12를 눌러 Console 탭을 보면 못 찾은 파일 이름이 빨간 글씨로 찍혀 있습니다. 클로드 코드에게 CSS를 index.html 안으로 합쳐달라고 하면 바로 해결됩니다.

/about 같은 하위 페이지에서 404가 납니다

1단계의 index.html 규칙이 그대로 적용된 결과입니다. /about은 파일 이름이 없는 폴더 주소라, 서버는 about 폴더 안의 index.html을 찾습니다. about.html이라는 파일은 이 규칙과 상관이 없어서 안 잡힙니다.

about이라는 폴더를 만들고 그 안에 index.html을 넣으세요. 그러면 /about/ 주소로 열립니다. 블로그처럼 페이지가 늘어나는 구조라면 처음부터 이 방식으로 잡는 게 낫습니다. 주소도 깔끔하고 검색엔진에도 유리합니다.

푸시했는데 사이트가 그대로입니다

브라우저와 배포망 양쪽에 이전 파일이 복사돼 있어서 그렇습니다. 매번 원본을 가져오면 느려지니까 일부러 복사해두는 구조입니다.

시크릿 창으로 열어보세요. 시크릿 창에서 바뀌어 있으면 정상이고, 잠시 후 일반 창에도 반영됩니다. 그래도 그대로면 Actions 탭에서 배포가 성공했는지 확인하세요.

CNAME 파일이 자꾸 사라집니다

도메인 연결이 풀리는 원인 1위입니다.

이유는 이렇습니다. CNAME 파일은 깃허브 웹 화면에서 생성됐기 때문에 깃허브에만 있고, 내 컴퓨터 폴더에는 없습니다. 그 상태에서 내 폴더 내용을 그대로 푸시하면, 깃은 "내 폴더에 없는 파일 = 지워진 파일"로 해석해서 깃허브에서도 지웁니다. 그 순간 서버는 이 저장소가 어느 도메인 담당인지 알 수 없게 되고, 사이트가 404로 바뀝니다.

깃허브에서 CNAME 파일 내용을 복사해서 내 폴더에도 똑같이 만들어두세요. 파일 이름은 확장자 없이 CNAME, 내용은 도메인 한 줄입니다. 한 번 맞춰두면 다시는 안 사라집니다.

도메인은 연결됐는데 www를 붙이면 안 들어가집니다

CNAME 레코드를 안 넣었거나, apex와 www 중 하나만 설정한 경우입니다. 둘 다 설정해야 깃허브가 나머지 하나를 자동으로 연결해줍니다.

수정하고 다시 올리는 법

한 번 세팅하고 나면 그다음부터는 이 3줄이 전부입니다.

git add .
git commit -m "수정 내용"
git push

1~2분 뒤 실제 사이트에 반영됩니다. 클로드 코드에게 "수정한 거 배포해줘"라고 해도 이 명령어를 대신 실행합니다.

전체 과정 한눈에 보기

표가 잘리면 좌우로 밀어서 보세요

처음 한 번은 1~9번을 다 지나야 하고, 그 뒤로는 평생 10번만 반복합니다.

정리

• 웹사이트가 뜨는 원리는 이름을 IP로 바꾸고, 그 서버가 폴더에서 파일을 찾는 것
• index.html은 취향이 아니라 서버 규칙. 하위 페이지도 폴더/index.html
• 배포 실패는 대부분 Jekyll 때문. .nojekyll부터 만들어보기
• 도메인은 깃허브 먼저, DNS 나중. 순서가 보안과 직결됨
• A 레코드 4개는 장애 대비용이라 전부 입력
• CNAME 파일은 도메인과 저장소를 잇는 유일한 근거. 내 폴더에도 만들어두기
• DNS는 복사본 유효기간 때문에 최대 24시간. 기다리는 게 맞음

클로드 코드로 화면을 만드는 것보다, 그 화면을 남이 볼 수 있는 주소로 만드는 게 사실 더 큰 고비입니다. 그 고비를 한 번 넘으면 다음부터는 만드는 족족 세상에 내보낼 수 있습니다.

자주 묻는 질문