이전 글에서는 기존 블로그 서비스를 이용하지 않고 개인 도메인의 웹사이트를 직접 만든 이유를 정리했다.

이번 글에서는 로컬 컴퓨터에서 만든 Astro 프로젝트가 어떻게 hekate.work라는 실제 웹사이트로 연결됐는지를 단계별로 정리한다.

Astro로 웹사이트 제작
→ GitHub에 코드 저장
→ Cloudflare Pages에서 배포
→ 개인 도메인 연결

1. Node.js 설치

Astro를 실행하려면 먼저 Node.js가 필요하다. Node.js를 설치하면 JavaScript 기반 패키지를 관리하는 npm도 함께 설치된다.

설치 후 PowerShell에서 버전을 확인했다.

node --version
npm.cmd --version

Windows PowerShell에서는 npm을 실행할 때 스크립트 실행 정책과 관련된 문제가 생길 수 있다. 이 경우 npm.cmd를 사용해 실행할 수 있다.

설치 과정에서 새로운 npm 버전이 있다는 안내도 나타났지만 이는 오류가 아니라 업데이트 알림이다. 먼저 현재 버전에서 프로젝트가 정상적으로 작동하는지를 확인했다.

2. 프로젝트를 만들 폴더로 이동

처음 Astro 프로젝트를 만들 때 PowerShell의 현재 위치가 C:\Windows\System32로 설정되어 있어 폴더 생성 권한 오류가 발생했다.

프로젝트를 저장할 사용자 문서 폴더로 이동한 뒤 다시 실행하자 정상적으로 진행됐다.

cd "$env:USERPROFILE\Documents"

현재 터미널의 위치는 다음 명령어로 확인할 수 있다.

Get-Location

오류 자체는 단순했다. 다만 AI가 알려주는 명령을 실행하는 데만 집중하면 에러 코드의 의미를 확인하지 않고 다음 해결책만 계속 요청할 수도 있겠다는 생각이 들었다.

특히 터미널 환경이 익숙하지 않은 경우라면 프로그램은 정상적으로 설치됐는데도 현재 폴더나 실행 세션의 차이 때문에 다음 단계로 넘어가지 못할 수 있다. 간단히 해결할 문제도 오래 걸리거나 여기서 작업을 포기하는 경우가 생길 수 있다.

AI에게 오류를 문의할 때는 현재 경로, 실행한 명령, 전체 오류 메시지와 마지막으로 정상 완료된 단계를 함께 전달하는 것이 좋다.

3. Astro 프로젝트 생성과 실행

문서 폴더에서 my-blog라는 Astro 프로젝트를 만들고 블로그 템플릿을 선택했다. 생성이 끝난 뒤 해당 폴더로 이동했다.

cd "$env:USERPROFILE\Documents\my-blog"

개발용 서버는 다음 명령어로 실행했다.

npm.cmd run dev

정상적으로 실행되면 브라우저에서 http://localhost:4321/을 열어 사이트를 확인할 수 있다.

터미널에 표시되는 watching for file changes...는 프로그램이 멈춘 것이 아니다. Astro가 파일 변경을 기다리고 있는 정상적인 상태다. Visual Studio Code에서 파일을 저장하면 변경사항이 브라우저에 반영된다.

4. Git 설치와 변경 이력 관리

Git을 설치했는데도 기존 PowerShell에서 명령어를 찾지 못하는 상황이 있었다. 전체 경로로는 정상적으로 실행됐다.

& "C:\Program Files\Git\cmd\git.exe" --version

설치 전에 열려 있던 터미널이 새 프로그램 경로를 아직 반영하지 못한 것이었다. PowerShell과 Visual Studio Code를 다시 실행한 뒤에는 git --version이 정상적으로 작동했다.

프로젝트 폴더에서는 Git 저장소를 초기화했다.

git init -b main
git add .
git commit -m "Initial commit"

LF will be replaced by CRLF라는 메시지도 나타났지만 이는 운영체제별 줄바꿈 방식에 대한 경고였다. 작업 실패를 의미하지는 않았다.

5. GitHub에 코드 저장

GitHub에 my-blog 저장소를 만들고 로컬 프로젝트를 연결했다.

git remote add origin https://github.com/hekatework/my-blog.git
git push -u origin main

첫 업로드에서는 브라우저를 통해 GitHub 인증을 완료했다. 이후 사이트 수정 과정은 다음 명령의 반복으로 단순해졌다.

git add .
git commit -m "변경 내용을 설명하는 문장"
git push

6. Cloudflare Pages에서 배포

Cloudflare Pages에서 GitHub 계정을 연결하고 my-blog 저장소를 선택했다.

Astro 프로젝트의 빌드 설정은 다음과 같이 입력했다.

Framework preset: Astro
Build command: npm run build
Build output directory: dist
Production branch: main

Cloudflare Pages가 GitHub의 코드를 가져와 웹사이트를 만들었고, 먼저 my-blog-76n.pages.dev 주소에서 결과를 확인했다.

이후 GitHub의 main 브랜치가 변경될 때마다 Cloudflare가 새로운 버전을 자동으로 배포한다.

7. 개인 도메인 연결

Cloudflare에서 구매한 hekate.work 도메인을 Pages 프로젝트에 연결했다.

DNS 설정 직후에는 상태가 Initializing 또는 Verifying으로 표시됐다. 오류가 아니라 도메인 정보와 SSL 인증서가 준비되는 과정이었다.

설정이 완료된 후 다음 두 주소가 활성화됐다.

https://hekate.work
https://www.hekate.work

8. 수정부터 배포까지의 반복 구조

기본 Astro 블로그를 개인 홈페이지와 포트폴리오 형태로 바꿨다. 영어와 한국어 페이지, 경력 소개, 언어 전환 버튼과 공유용 이미지도 추가했다.

수정한 내용은 먼저 로컬에서 확인하고, 문제가 없으면 GitHub에 올렸다.

Visual Studio Code에서 수정
→ 로컬에서 확인
→ Git에 변경 이력 저장
→ GitHub에 업로드
→ Cloudflare Pages 자동 배포
→ hekate.work에 반영

AI가 있어도 환경의 맥락은 직접 확인해야 한다

ChatGPT는 명령어를 찾고 오류의 원인을 좁히는 데 유용했다. 하지만 사용자의 컴퓨터 상태를 자동으로 모두 알고 있는 것은 아니다.

같은 명령어도 현재 폴더, 프로그램 설치 전후의 터미널 세션, 실행 중인 서버와 운영체제 권한에 따라 다른 결과가 나올 수 있다.

이번 과정에서 유용했던 확인 순서는 다음과 같다.

1. 현재 폴더를 확인한다.
2. 프로그램 버전을 확인한다.
3. 전체 오류 메시지를 읽는다.
4. 마지막으로 성공한 단계를 확인한다.
5. 한 번에 한 가지씩 변경한다.

현재 사이트의 기본 구조는 완성됐다. 앞으로는 Markdown으로 글을 작성하고 GitHub에 반영하면 Cloudflare Pages가 자동으로 배포한다.

처음에는 여러 도구를 연결해야 했지만 구조가 완성된 뒤의 운영 과정은 단순하다.

글 작성
→ 저장
→ GitHub에 업로드
→ 자동 배포

이번 작업을 통해 Node.js, Astro, GitHub, Cloudflare Pages와 DNS가 어떤 역할을 하고 어떻게 연결되는지 직접 확인할 수 있었다. 개발 실무자가 아니더라도 요구사항을 정의하고 결과를 판단할 수 있다면 AI의 도움을 받아 자신이 소유하는 웹사이트를 구축할 수 있다는 것도 확인했다.