Ghost 블로그 업그레이드 완벽 가이드 - Docker 환경에서 안전하게 버전 올리기

1. 왜 업그레이드가 중요한가

Ghost는 활발하게 개발되는 오픈소스 프로젝트로, 정기적인 업데이트가 필요합니다.

1.1 업그레이드의 이점

업그레이드 이유:
├── 보안 패치 적용
├── 새로운 기능 사용 (ActivityPub, Analytics 등)
├── 버그 수정
├── 성능 개선
└── 장기 지원 (LTS) 보장

1.2 주요 버전 변경사항

1.3 업그레이드 주기 권장

2. 업그레이드 전 체크리스트

2.1 필수 확인 사항

[ ] 현재 Ghost 버전 확인
[ ] 최신 버전 릴리즈 노트 확인
[ ] 데이터베이스 백업 완료
[ ] 콘텐츠(이미지, 테마) 백업 완료
[ ] 충분한 디스크 공간 확인
[ ] 롤백 계획 수립

2.2 현재 버전 확인

# Ghost 컨테이너에서 버전 확인
docker exec ghost ghost --version
# Ghost-CLI version: 1.26.1
# Ghost version: 6.13.2 (at /var/lib/ghost)

또는 Ghost Admin에서:

• Settings → 하단 About 섹션

2.3 릴리즈 노트 확인

새 버전의 변경사항을 반드시 확인하세요:

• Ghost Changelog
• Ghost GitHub Releases

주의: 메이저 버전 업그레이드(5.x → 6.x)는 Breaking Changes가 있을 수 있습니다. 릴리즈 노트를 꼼꼼히 읽어보세요.

3. 백업 수행

업그레이드 전 백업은 필수입니다. 3편에서 설정한 백업 스크립트를 활용합니다.

3.1 수동 백업 실행

# 백업 스크립트 실행
~/scripts/backup.sh

3.2 백업 파일 확인

ls -la ~/backup/
# ghost-db-20260121_120000.sql
# ghost-content-20260121_120000.tar.gz
# docker-compose-20260121_120000.yml

3.3 백업 파일 별도 보관 (권장)

# 업그레이드용 백업을 별도 디렉토리에 복사
mkdir -p ~/backup/pre-upgrade
cp ~/backup/ghost-db-*.sql ~/backup/pre-upgrade/
cp ~/backup/ghost-content-*.tar.gz ~/backup/pre-upgrade/

4. Docker 이미지 업그레이드 방법

4.1 방법 1: latest 태그 사용 (자동 업그레이드)

docker-compose.yml에서 latest 태그를 사용하면 pull 시 최신 버전을 받습니다.

services:
  ghost:
    image: ghost:6-alpine  # 6.x 최신 버전
    # 또는
    image: ghost:latest    # 가장 최신 버전

업그레이드 명령:

cd ~/docker/ghost

# 최신 이미지 pull
docker compose pull

# 컨테이너 재생성
docker compose up -d

4.2 방법 2: 특정 버전 지정 (권장)

프로덕션 환경에서는 특정 버전을 명시하는 것이 안전합니다.

services:
  ghost:
    image: ghost:6.13.2-alpine  # 특정 버전 지정

업그레이드 명령:

cd ~/docker/ghost

# docker-compose.yml에서 버전 수정
# ghost:6.10.0-alpine → ghost:6.13.2-alpine

# 이미지 pull 및 재생성
docker compose pull
docker compose up -d

4.3 업그레이드 후 확인

# 컨테이너 상태 확인
docker ps

# 버전 확인
docker exec ghost ghost --version

# 로그 확인 (에러 없는지)
docker logs ghost --tail 50

5. 메이저 버전 업그레이드 (5.x → 6.x)

메이저 버전 업그레이드는 더 신중하게 진행해야 합니다.

5.1 Ghost 6.0 주요 변경사항

5.2 업그레이드 절차

# 1. 백업 확인
ls -la ~/backup/pre-upgrade/

# 2. 컨테이너 중지
cd ~/docker/ghost
docker compose down

# 3. docker-compose.yml 수정
# image: ghost:5-alpine → ghost:6-alpine

# 4. 새 이미지 pull
docker compose pull

# 5. 컨테이너 시작
docker compose up -d

# 6. 마이그레이션 로그 확인
docker logs ghost -f

5.3 마이그레이션 확인

메이저 업그레이드 시 Ghost는 자동으로 데이터베이스 마이그레이션을 수행합니다.

# 로그에서 마이그레이션 완료 확인
docker logs ghost | grep -i migration
# [INFO] Migrations complete

5.4 기능 확인

업그레이드 후 새 기능 활성화:

1. Ghost Admin → Settings → Growth → Network (ActivityPub)
2. 대시보드에서 Analytics 확인

6. 롤백 방법

업그레이드 후 문제가 발생하면 롤백합니다.

6.1 컨테이너 롤백

cd ~/docker/ghost

# 1. 컨테이너 중지
docker compose down

# 2. docker-compose.yml에서 이전 버전으로 수정
# ghost:6.13.2-alpine → ghost:6.10.0-alpine

# 3. 이전 이미지로 시작
docker compose up -d

6.2 데이터베이스 롤백 (필요시)

데이터베이스 스키마가 변경된 경우 백업에서 복원해야 합니다.

# 1. 컨테이너 중지
docker compose down

# 2. 데이터베이스 볼륨 삭제
docker volume rm ghost_ghost-db-data

# 3. 새 볼륨 생성 및 DB 시작
docker volume create ghost_ghost-db-data
docker compose up -d ghost-db
sleep 15  # DB 초기화 대기

# 4. 백업에서 복원
docker exec -i ghost-db mysql -u ghost -p${GHOST_DB_PASSWORD} ghost < ~/backup/pre-upgrade/ghost-db-*.sql

# 5. 콘텐츠 복원
docker volume rm ghost_ghost-content
docker volume create ghost_ghost-content
docker run --rm \
  -v ghost_ghost-content:/data \
  -v ~/backup/pre-upgrade:/backup \
  alpine tar xzf /backup/ghost-content-*.tar.gz -C /data

# 6. Ghost 시작 (이전 버전)
docker compose up -d

6.3 롤백 확인

# 버전 확인
docker exec ghost ghost --version

# 사이트 접속 테스트
curl -s https://blog.example.com | head -5

7. 자동 업그레이드 설정 (선택)

7.1 Watchtower 사용

Watchtower는 Docker 컨테이너를 자동으로 업데이트하는 도구입니다.

# docker-compose.yml에 추가
services:
  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_SCHEDULE=0 0 4 * * *  # 매일 새벽 4시
      - WATCHTOWER_LABEL_ENABLE=true
    command: --label-enable

  ghost:
    image: ghost:6-alpine
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
    # ... 기존 설정

주의: 프로덕션 환경에서 자동 업그레이드는 위험할 수 있습니다. 패치 버전만 자동 업그레이드하고, 마이너/메이저는 수동으로 진행하세요.

7.2 업그레이드 알림 설정

수동 업그레이드를 선호한다면, 새 버전 알림만 받을 수 있습니다:

# GitHub Watch → Releases only
# https://github.com/TryGhost/Ghost

8. 트러블슈팅

8.1 업그레이드 후 500 에러

원인: 데이터베이스 마이그레이션 실패

# 로그 확인
docker logs ghost | grep -i error

# 해결: 롤백 후 재시도

8.2 "Ghost was able to start, but errored during boot"

원인: 설정 파일 호환성 문제

# 환경변수 확인
docker exec ghost env | grep -i ghost

# 해결: 새 버전의 환경변수 요구사항 확인

8.3 테마 호환성 문제

원인: 테마가 새 버전과 호환되지 않음

# 기본 테마로 전환
# Ghost Admin → Settings → Design → Change theme → Casper

8.4 플러그인/통합 문제

원인: 서드파티 통합이 새 버전과 호환되지 않음

# Ghost Admin → Settings → Integrations
# 문제 있는 통합 비활성화 후 테스트

9. 핵심 개념 정리

10. 베스트 프랙티스

체크리스트

• [ ] 업그레이드 전 반드시 백업
• [ ] 릴리즈 노트 확인
• [ ] 테스트 환경에서 먼저 테스트 (가능하다면)
• [ ] 트래픽이 적은 시간대에 진행
• [ ] 롤백 계획 수립
• [ ] 업그레이드 후 기능 테스트

권장 사항

11. FAQ

Q: 업그레이드 중 데이터가 손실될 수 있나요?
A: Docker 볼륨을 사용하면 컨테이너 재생성 시에도 데이터가 유지됩니다. 하지만 백업은 필수입니다.

Q: 다운타임 없이 업그레이드할 수 있나요?
A: 단일 서버에서는 어렵습니다. 컨테이너 재시작 동안 수 초 ~ 수십 초의 다운타임이 발생합니다.

Q: 여러 버전을 건너뛰어 업그레이드해도 되나요?
A: 네, Ghost는 누적 마이그레이션을 지원합니다. 하지만 메이저 버전은 순차적으로 하는 것이 안전합니다 (5.x → 6.x).

Q: MySQL도 함께 업그레이드해야 하나요?
A: Ghost 버전에 따라 다릅니다. Ghost 6.x는 MySQL 8.0을 권장합니다. MySQL 업그레이드는 별도로 신중하게 진행하세요.

Q: 테마와 플러그인도 업데이트해야 하나요?
A: 테마는 Ghost 버전과 호환성을 확인하세요. 공식 테마(Casper)는 자동으로 호환됩니다.

12. 다음 단계

Ghost 업그레이드 방법을 익혔습니다! 다음 글에서는 ActivityPub으로 블로그를 Fediverse에 연결하는 방법을 다룹니다.

시리즈 목차:

1. Oracle Cloud 무료 서버 세팅
2. Ghost 블로그 Docker 설치
3. Ghost 블로그 백업 자동화
4. 검색엔진 등록 (Google/Naver)
5. Ghost 6.0 업그레이드 ← 현재 글
6. Ghost ActivityPub 설정 (Fediverse)
7. Ghost Analytics 설정 (Tinybird)

13. 참고 자료

• Ghost Changelog
• Ghost GitHub Releases
• Ghost Docker Hub
• Watchtower 문서