Dokploy와 Nixpacks를 활용한 Astro 프로젝트 배포 및 캐시 최적화를 통한 빌드 속도 향상

1. Dokploy 설정

Dokploy는 오픈 소스 및 셀프 호스팅이 가능한 배포 플랫폼입니다. Docker와 Traefik 기반으로 구축되었으며, Heroku, Vercel, Netlify의 무료 대안으로 설계되었습니다.

1. 새 프로젝트 생성 및 GitHub 저장소 연결

2. 환경 변수 설정

NIXPACKS_NODE_VERSION=22
NIXPACKS_PNPM_STORE_PATH=/root/.local/share/pnpm/store/v3
NIXPACKS_INSTALL_CACHE_DIRS=/app/node_modules
NIXPACKS_BUILD_CACHE_DIRS=/app/node_modules/.cache,/app/astro_cache

3. 캐시 자동 정리 비활성화

프로젝트 서비스 → Clean Cache: 비활성화
웹 서버 → Daily Docker Cleanup: 비활성화

2. Nixpacks 빌드 엔진

Nixpacks는 Railway가 개발한 오픈 소스 빌드 도구로, 소스 코드를 표준 Docker 이미지로 빌드할 수 있습니다. Dokploy는 기본적으로 Nixpacks를 사용하며, nixpacks.toml 또는 nixpacks.json 파일을 통해 설정할 수 있습니다.

프로젝트 루트에 nixpacks.toml 파일을 생성하고, 캐시 디렉토리를 설정하세요.

설정 우선순위 (낮음 → 높음)

기본 Provider 로직
nixpacks.toml
환경 변수
CLI 인자

주요 환경 변수

변수명	설명
`NIXPACKS_INSTALL_CMD`	설치 명령어 오버라이드
`NIXPACKS_BUILD_CMD`	빌드 명령어 오버라이드
`NIXPACKS_START_CMD`	시작 명령어 오버라이드
`NIXPACKS_PKGS`	추가 Nix 패키지 설치
`NIXPACKS_APT_PKGS`	추가 Apt 패키지 설치
`NIXPACKS_INSTALL_CACHE_DIRS`	설치 시 캐시 디렉토리
`NIXPACKS_BUILD_CACHE_DIRS`	빌드 시 캐시 디렉토리
`NIXPACKS_NO_CACHE`	캐시 비활성화 (비추천)
`NIXPACKS_CONFIG_FILE`	설정 파일 지정
`NIXPACKS_DEBIAN`	Debian 기반 이미지 사용

3. Astro 프로젝트 설정

Astro는 블로그, 마케팅 페이지, 전자상거래 사이트 등 콘텐츠 중심 정적 웹사이트에 적합한 최신 웹 프레임워크입니다. 이미지 및 정적 리소스가 많을 경우 빌드 속도가 느려질 수 있는데, 캐시를 활용하면 이를 크게 개선할 수 있습니다.

1. Astro에서 캐시 디렉토리 지정

Astro 설정 파일(astro.config.mjs)에 캐시 디렉토리를 지정하세요. 상대 경로나 절대 경로 모두 사용 가능합니다.

// astro.config.mjs
export default defineConfig({
  cacheDir: './astro_cache',
});

2. Nixpacks 캐시 구성 파일 작성

Astro 프로젝트 루트에 nixpacks.toml 파일을 작성하고 캐시 디렉토리와 빌드 명령어를 설정하세요.

# Node.js 및 pnpm 버전 명시
[phases.setup]
nixPkgs = ["nodejs_22", "pnpm"]

# pnpm 캐시를 활용한 의존성 설치
[phases.install]
cmds = ["pnpm install --frozen-lockfile"]
cacheDirectories = ["/root/.local/share/pnpm/store/v3"]

# Astro 빌드 및 캐시 디렉토리 설정
[phases.build]
cmds = ["pnpm run build"]
cacheDirectories = [
  "node_modules/.cache",
  "astro_cache"
]

# 시작 명령어 (NGINX로 dist 디렉토리 제공 가정)
[start]
cmd = "echo '빌드 완료. dist 디렉토리를 NGINX로 서비스하세요.'"

4. Docker 빌드 컨텍스트 최적화

Astro 프로젝트 루트에 .dockerignore 파일을 추가하세요:

node_modules
astro_cache
dist
*.log
.DS_Store
.vscode
.env*

5. 배포 및 캐시 확인

Dokploy에서 자동 배포 후, 빌드 로그에서 아래 항목을 확인하여 캐시가 적용되었는지 검증하세요.

1. 캐시 마운트와 함께 실행되는 빌드 명령어

RUN --mount=type=cache,id=xxxx-node_modules/cache,target=/app/node_modules/.cache \
    --mount=type=cache,id=xxxx-astro_cache,target=/app/astro_cache \
    pnpm run build

2. Astro가 캐시 항목을 재활용하는 로그 출력 (특히 이미지 최적화)

▶ /_astro/202409272055577_Z2smeTW.avif (reused cache entry)
▶ /_astro/202409272055575_Z2wPyJN.avif (reused cache entry)
▶ /_astro/202409272055577_1IgP6g.avif (reused cache entry)