최근 개인 기술 블로그를 구축하면서, 빠르고 가벼운 정적 사이트 제너레이터(SSG)인 Astro와 무료 호스팅 서비스인 GitHub Pages의 조합에 주목했다. 특히, 나만의 커스텀 도메인을 사용하여 전문성을 더하는 과정은 기술적인 탐구와 삽질의 연속이었다. 이 글에서는 Astro 프로젝트를 생성하고, GitHub Pages에 배포하며, 최종적으로 커스텀 도메인을 성공적으로 연동하는 과정을 상세히 기록했다.

1. Astro 프로젝트 초기 설정

Astro는 모던 웹 개발의 복잡성을 줄이고, 성능 최적화에 강점을 가진 프레임워크이다. 새로운 프로젝트를 시작하는 것은 매우 간단하다.

새로운 Astro 프로젝트 생성

pnpm create astro@latest

설치 마법사(astro.build/wizards/create-astro)가 나타나면, 블로그 템플릿을 선택하거나 빈 프로젝트를 선택하여 진행하면 된다. 본인의 경우, 블로그 템플릿을 기반으로 시작했다.

프로젝트 생성이 완료되면, 개발 서버를 실행하여 초기 상태를 확인한다.

pnpm dev

http://localhost:4321에서 Astro의 기본 페이지를 확인할 수 있다.

2. GitHub Pages 배포를 위한 Astro 설정

GitHub Pages는 정적 웹사이트를 무료로 호스팅할 수 있는 훌륭한 서비스이다. Astro 프로젝트를 GitHub Pages에 배포하기 위해서는 몇 가지 설정이 필요하다.

2.1. `astro.config.mjs` 설정

GitHub Pages는 일반적으로 https://<USERNAME>.github.io/<REPOSITORY_NAME>/와 같은 서브 경로에 사이트를 배포한다. 따라서 Astro 프로젝트의 빌드 경로를 이 base 경로에 맞추어 주어야 한다.

// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwind from "@astrojs/tailwind";

// https://astro.build/config
export default defineConfig({
  site: 'https://devbj.github.io', // 본인의 GitHub Pages URL로 변경
  base: '/<REPOSITORY_NAME>', // 본인의 레포지토리 이름으로 변경 (예: /devbj-log)
  integrations: [tailwind()]
});

site는 배포될 웹사이트의 전체 URL을, base는 GitHub Pages의 서브 경로를 의미한다. base를 설정하지 않으면, 모든 리소스(CSS, JS, 이미지 등) 경로가 / 기준으로 참조되어 404 Not Found 오류가 발생할 수 있다.

2.2. 배포 스크립트 작성

GitHub Pages는 gh-pages 브랜치 또는 main 브랜치의 /docs 폴더를 통해 정적 파일을 호스팅할 수 있다. 본인은 gh-pages 브랜치를 사용하는 방식을 선호하여, 배포 자동화를 위한 간단한 스크립트를 작성했다.

deploy.sh 파일을 프로젝트 루트에 생성하고 다음 내용을 추가했다.

#!/usr/bin/env sh

# 에러 발생 시 즉시 종료
set -e

# Astro 프로젝트 빌드
echo "Astro 프로젝트 빌드를 시작합니다..."
pnpm run build

# 빌드된 디렉토리로 이동 (기본적으로 dist 폴더에 생성됨)
cd dist

# GitHub Pages에 배포
echo "GitHub Pages에 배포를 시작합니다..."

# 초기화 및 커밋
git init
git add -A
git commit -m 'deploy'

# <USERNAME>.github.io/<REPOSITORY_NAME> 형식의 원격 저장소에 푸시
# <USERNAME>과 <REPOSITORY_NAME>을 본인의 정보로 변경해야 함
# 예: git push -f git@github.com:devbj/devbj-log.git main:gh-pages
git push -f git@github.com:<USERNAME>/<REPOSITORY_NAME>.git main:gh-pages

echo "배포 완료!"

# 이전 디렉토리로 복귀
cd -

이 스크립트를 실행 가능하게 만들고 (chmod +x deploy.sh), package.json에 스크립트로 등록한다.

// package.json
{
  "name": "devbj-log",
  "type": "module",
  "version": "0.0.1",
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro",
    "deploy": "./deploy.sh" // 추가된 배포 스크립트
  },
  // ...
}

이제 pnpm run deploy 명령 한 번으로 빌드와 배포를 동시에 수행할 수 있다.

2.3. GitHub Repository 설정

GitHub에서 해당 Repository의 Settings → Pages 메뉴로 이동하여 Source를 Deploy from a branch로 설정하고, Branch를 gh-pages로, folder를 / (root)로 지정한다.

설정이 완료되면 잠시 후 GitHub Pages URL을 통해 배포된 사이트를 확인할 수 있다.

3. 커스텀 도메인 연동

이제 devbj.github.io/devbj-log와 같은 기본 URL 대신, devbj.dev와 같은 나만의 도메인을 연결할 차례이다.

3.1. `CNAME` 파일 생성

GitHub Pages는 커스텀 도메인을 인식하기 위해 프로젝트의 public 폴더 안에 CNAME 파일을 요구한다. 이 파일에는 사용할 커스텀 도메인만 명시한다.

public/CNAME 파일 생성:

devbj.dev

3.2. GitHub Repository 설정 (재확인)

GitHub Repository의 Settings → Pages 메뉴에서 Custom domain 섹션에 구매한 도메인(예: devbj.dev)을 입력한다.

이후 Enforce HTTPS 옵션이 자동으로 활성화되는지 확인한다. 만약 바로 활성화되지 않으면, 잠시 기다려야 한다. GitHub Pages가 도메인에 대한 SSL 인증서를 자동으로 발급하기 때문이다.

3.3. DNS 설정

가장 중요한 단계는 도메인 구매처(또는 Cloudflare와 같은 DNS 관리 서비스)에서 DNS 레코드를 설정하는 것이다.

서브 도메인 없이 루트 도메인(예: devbj.dev)을 사용하는 경우:

A 레코드 설정:
- Host: @ (또는 비워둠)
- Value: 185.199.108.153
- Value: 185.199.109.153
- Value: 185.199.110.153
- Value: 185.199.111.153
  이 네 개의 IP 주소는 GitHub Pages 서버의 IP이다. GitHub Docs에서 최신 IP를 확인할 수 있다.

www 서브 도메인을 함께 사용하는 경우 (예: www.devbj.dev):

CNAME 레코드 설정:
- Host: www
- Value: <USERNAME>.github.io (본인의 GitHub Pages 기본 도메인으로 변경, 예: devbj.github.io)

DNS 변경 사항이 전 세계에 전파되는 데는 몇 분에서 최대 24시간이 소요될 수 있다. dig 명령어나 nslookup을 통해 변경 사항을 확인할 수 있다.

dig devbj.dev
dig www.devbj.dev

DNS 전파가 완료되고 GitHub Pages 설정이 정상적으로 적용되면, 입력한 커스텀 도메인을 통해 Astro 기반의 기술 블로그에 접속할 수 있게 된다.

4. 트러블슈팅 및 팁

base 경로 문제: GitHub Pages에 배포했으나 CSS나 JS 파일이 로드되지 않는다면 astro.config.mjs의 base 경로 설정이 올바른지 다시 확인해야 한다. https://<USERNAME>.github.io/<REPOSITORY_NAME>/ 형식의 URL에서는 <REPOSITORY_NAME>이 base가 된다.
CNAME 파일 누락/오류: public 폴더 내의 CNAME 파일이 없거나, 파일 내용에 오타가 있으면 커스텀 도메인 연동이 실패한다. 파일에는 오직 도메인 이름만 포함되어야 한다.
DNS 전파 시간: DNS 변경 후 바로 적용되지 않는다고 당황하지 말자. 잠시 시간을 두고 기다리는 것이 필요하다.
HTTPS 강제 적용: GitHub Pages는 기본적으로 HTTPS를 지원한다. 커스텀 도메인 설정 후 Enforce HTTPS 옵션이 활성화되지 않았다면, 브라우저 캐시를 지우고 다시 시도하거나, GitHub Pages 설정 페이지를 몇 번 새로고침 해볼 필요가 있다.

결론

Astro와 GitHub Pages, 그리고 커스텀 도메인의 조합은 빠르고 효율적인 기술 블로그를 구축하는 데 매우 강력한 도구임을 확인했다. 초기 설정 과정에서 base 경로와 DNS 설정에 대한 이해가 중요하며, 이 부분에서 약간의 삽질이 발생할 수 있지만, 한 번 구축해두면 유지보수가 매우 용이하다는 장점이 있다. 이 과정을 통해 나만의 전문적인 기술 블로그를 성공적으로 운영할 수 있게 되었다.

DevBJ | No Bio, Just Log 기술 삽질로그

Astro와 GitHub Pages: 커스텀 도메인으로 기술 블로그 배포하기