Docker에서 실행하기

Docker에서 헤드리스 브라우저를 실행하려면 많은 설정이 필요합니다. 하지만 걱정하지 마세요. 이미 사용할 수 있는 기본 이미지를 만들어 두었습니다. 우리는 Apify 플랫폼에서 매일 이 이미지들을 사용하고 있습니다.

모든 이미지는 GitHub 저장소와 DockerHub에서 확인할 수 있습니다.

개요

브라우저는 크기가 크기 때문에, 다양한 요구 사항에 맞는 여러 이미지를 제공하고 있습니다. 다음은 Docker 이미지의 전체 목록입니다.

apify/actor-node
apify/actor-node-puppeteer-chrome
apify/actor-node-playwright
apify/actor-node-playwright-chrome
apify/actor-node-playwright-firefox
apify/actor-node-playwright-webkit

버전 관리

각 이미지는 이미지 유형에 따라 최대 2개의 버전 태그를 가집니다. Node.js 버전용 태그와 사전 설치된 웹 자동화 라이브러리 버전용 태그입니다. 버전 태그 없이 이미지 이름만 사용하면 항상 최신 버전을 받게 됩니다.

프로덕션 환경의 Dockerfile에서는 최소한 Node.js 버전 태그를 사용하는 것을 권장합니다. 이렇게 하면 향후 Node.js 업데이트로 인한 자동화 작업의 중단을 방지할 수 있습니다.

Node.js 버전 관리

하위 호환성을 보장하기 위해 여러 Node.js 버전으로 이미지를 빌드합니다. 현재 Node.js 버전 16과 18이 지원됩니다 (이전 버전은 DockerHub 참조). 원하는 버전을 선택하려면 해당 숫자를 이미지 태그로 사용하세요.

# Node.js 20 사용
FROM apify/actor-node:20

자동화 라이브러리 버전 관리

puppeteer 또는 playwright가 이름에 포함된 모든 이미지는 사전 설치된 자동화 라이브러리의 버전도 태그로 표시됩니다. 예를 들어, apify/actor-node-puppeteer-chrome:20-22.1.0은 Node.js 20과 Puppeteer v22.1.0이 포함되어 있습니다. 이 이미지에 다른 버전의 Puppeteer를 설치하려고 하면, 사전 설치된 Chromium 버전과 puppeteer에 번들로 제공되는 Chromium 버전이 일치하지 않아 호환성 문제가 발생할 수 있습니다.

마찬가지로 apify/actor-node-playwright-firefox:14-1.21.1은 Node.js 14에서 실행되며 v1.21.1과 함께 제공되는 Firefox 버전이 사전 설치되어 있습니다.

태그 없이 apify/actor-node-puppeteer-chrome을 설치하면 최신 버전의 Node.js와 puppeteer가 설치됩니다.

프리릴리스 태그

변경 사항을 테스트하기 위해 이미지의 프리릴리스 버전도 빌드합니다. 일반적으로 beta 접미사로 표시되지만 필요에 따라 다를 수 있습니다. 프리릴리스 버전을 사용하려면 다음과 같이 할 수 있습니다:

# 라이브러리 버전 없이
FROM apify/actor-node:20-beta

# 라이브러리 버전 포함
FROM apify/actor-node-playwright-chrome:20-1.10.0-beta

모범 사례

Node.js 버전 태그는 항상 사용해야 합니다.
자동화 라이브러리 버전 태그는 보안 강화를 위해 사용해야 합니다.
package.json 파일에서는 자동화 라이브러리 버전으로 별표 *를 사용해야 합니다.

이렇게 하면 빌드 시 사전 설치된 Puppeteer나 Playwright 버전이 재설치되지 않습니다. 이는 중요한데, 이러한 라이브러리들은 특정 브라우저 버전에서만 작동이 보장되며, 해당 브라우저들은 이미지에 사전 설치되어 있기 때문입니다.

FROM apify/actor-node-playwright-chrome:20

{
    "dependencies": {
        "crawlee": "^3.0.0",
        "playwright": "*"
    }
}

이미지 크기에 대한 경고

브라우저는 매우 큽니다. 모든 브라우저가 필요하지 않다면 필요한 브라우저만 포함된 작은 이미지를 사용하는 것이 좋습니다.

새로운 의존성을 설치할 때도 주의해야 합니다. actor-node-puppeteer-chrome 이미지에 Playwright를 설치하는 것을 막을 수는 없지만, 결과적으로 이미지 크기가 약 3배로 커지고 다운로드와 빌드 속도가 매우 느려질 것입니다.

필요한 것만 사용하면 합리적인 빌드 및 시작 시간을 얻을 수 있습니다.

Apify Docker 이미지

actor-node

Alpine Linux 기반의 가장 작은 이미지입니다. 브라우저를 포함하지 않으므로 CheerioCrawler와 함께 사용하기에 가장 적합합니다. 빠른 빌드와 컨테이너 시작 시간이 장점입니다.

PuppeteerCrawler, PlaywrightCrawler 및 기타 브라우저 기반 기능은 이 이미지에서 작동하지 않습니다.

FROM apify/actor-node:20

actor-node-puppeteer-chrome

이 이미지는 Puppeteer(Chromium)와 Chrome 브라우저를 포함합니다. CheerioCrawler와 PuppeteerCrawler와 함께 사용할 수 있지만, PlaywrightCrawler와는 사용할 수 없습니다.

기본적으로 XVFB를 지원하므로 headless와 headful 브라우저를 모두 실행할 수 있습니다.

FROM apify/actor-node-puppeteer-chrome:20

actor-node-playwright

모든 Playwright 브라우저(Chromium, Chrome, Firefox, WebKit)를 실행할 수 있는 매우 큰 이미지입니다. 모든 것이 설치되어 있습니다. 여러 브라우저로 개발하거나 테스트해야 하는 경우에 적합하지만, 대부분의 경우 아래의 전문화된 이미지를 사용하는 것이 좋습니다.

FROM apify/actor-node-playwright:20

actor-node-playwright-chrome

actor-node-puppeteer-chrome와 비슷하지만 Playwright용입니다. CheerioCrawler와 PlaywrightCrawler는 사용할 수 있지만, PuppeteerCrawler는 사용할 수 없습니다.

이미지를 작게 유지하기 위해 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD 환경 변수를 사용하여 추가 브라우저 설치를 차단합니다. 더 많은 브라우저가 필요한 경우 actor-node-playwright 이미지를 사용하거나 이 환경 변수를 재정의하세요.

기본적으로 XVFB를 지원하므로 headless와 headful 브라우저를 모두 실행할 수 있습니다.

FROM apify/actor-node-playwright-chrome:20

actor-node-playwright-firefox

actor-node-playwright-chrome와 동일한 개념이지만 Firefox가 사전 설치되어 있습니다.

FROM apify/actor-node-playwright-firefox:20

actor-node-playwright-webkit

actor-node-playwright-chrome와 동일한 개념이지만 WebKit이 사전 설치되어 있습니다.

FROM apify/actor-node-playwright-webkit:20

Dockerfile 예제

위의 이미지를 사용하려면 Dockerfile이 필요합니다. 이 예제를 사용하거나 Crawlee CLI로 프로젝트를 생성하면 프로젝트 폴더에 적절한 Dockerfile이 자동으로 추가됩니다.

Node+JavaScript
Node+TypeScript
Browser+JavaScript
Browser+TypeScript

# 기본 Docker 이미지를 지정합니다. 사용 가능한 이미지에 대한
# 자세한 내용은 https://crawlee.dev/docs/guides/docker-images 에서
# 확인할 수 있습니다. Docker Hub의 다른 이미지도 사용할 수 있습니다.
FROM apify/actor-node:20

# Docker 레이어 캐시를 활용하여 빌드 속도를 높이기 위해
# package.json과 package-lock.json만 먼저 복사합니다.
COPY package*.json ./

# NPM 패키지를 설치하되, 이미지 크기를 최소화하기 위해
# 선택적 종속성과 개발 종속성은 제외합니다.
# 로그는 최소화하고 디버깅을 위한 종속성 트리를 출력합니다.
RUN npm --quiet set progress=false \
    && npm install --omit=dev --omit=optional \
    && echo "설치된 NPM 패키지:" \
    && (npm list --omit=dev --all || true) \
    && echo "Node.js 버전:" \
    && node --version \
    && echo "NPM 버전:" \
    && npm --version

# 마지막으로 소스 코드가 포함된 나머지 파일과 디렉터리를 복사합니다.
# NPM 설치 후에 이 작업을 수행하므로, 대부분의 소스 파일 변경 시
# 빠른 빌드가 가능합니다.
COPY . ./


# 이미지를 실행합니다.
CMD npm start --silent

# 기본 Docker 이미지를 지정합니다. 사용 가능한 이미지에 대해
# 자세히 알아보려면 https://crawlee.dev/docs/guides/docker-images 를 참조하세요.
# Docker Hub의 다른 이미지도 사용할 수 있습니다.
FROM apify/actor-node:20 AS builder

# Docker 레이어 캐시를 활용하여 빌드 속도를 높이기 위해
# package.json과 package-lock.json만 복사합니다.
COPY package*.json ./

# 모든 의존성을 설치합니다. 설치 속도를 높이기 위해 감사는 건너뜁니다.
RUN npm install --include=dev --audit=false

# 기본 이미지에 설정된 사용자로
# 소스 파일을 복사합니다.
COPY . ./

# 모든 의존성을 설치하고 프로젝트를 빌드합니다.
# 설치 속도를 높이기 위해 감사는 건너뜁니다.
RUN npm run build

# 최종 이미지 생성
FROM apify/actor-node:20

# builder 이미지에서 빌드된 JS 파일만 복사
COPY --from=builder /usr/src/app/dist ./dist

# Docker 레이어 캐시를 활용하여 빌드 속도를 높이기 위해
# package.json과 package-lock.json만 복사합니다.
COPY package*.json ./

# NPM 패키지를 설치하되, 이미지 크기를 작게 유지하기 위해
# 선택적 의존성과 개발 의존성은 제외합니다.
# 로깅을 최소화하고 디버깅을 위해 의존성 트리를 출력합니다.
RUN npm --quiet set progress=false \
    && npm install --omit=dev --omit=optional \
    && echo "설치된 NPM 패키지:" \
    && (npm list --omit=dev --all || true) \
    && echo "Node.js 버전:" \
    && node --version \
    && echo "NPM 버전:" \
    && npm --version

# 마지막으로 나머지 소스 코드 파일과 디렉터리를 복사합니다.
# NPM 설치 후에 이 작업을 수행하므로, 대부분의 소스 파일 변경 시
# 빠른 빌드가 가능합니다.
COPY . ./

# 이미지를 실행합니다.
CMD npm run start:prod --silent

이 예제는 Playwright용입니다. Puppeteer를 사용하려면 FROM 선언에서 playwright를 puppeteer로 바꾸기만 하면 됩니다.

# 기본 Docker 이미지를 지정합니다. 사용 가능한 이미지에 대한
# 자세한 내용은 https://crawlee.dev/docs/guides/docker-images 에서
# 확인하실 수 있습니다. Docker Hub의 다른 이미지도 사용 가능합니다.
FROM apify/actor-node-playwright-chrome:20

# Docker 레이어 캐시를 활용하여 빌드 속도를 높이기 위해
# package.json과 package-lock.json만 먼저 복사합니다.
COPY --chown=myuser package*.json ./

# NPM 패키지를 설치하되, 이미지 크기를 최소화하기 위해
# 선택적 종속성과 개발 종속성은 제외합니다.
# 로그는 최소화하고 디버깅을 위한 종속성 트리를 출력합니다.
RUN npm --quiet set progress=false \
    && npm install --omit=dev --omit=optional \
    && echo "설치된 NPM 패키지:" \
    && (npm list --omit=dev --all || true) \
    && echo "Node.js 버전:" \
    && node --version \
    && echo "NPM 버전:" \
    && npm --version

# 마지막으로 소스 코드가 포함된 나머지 파일과 디렉터리를 복사합니다.
# NPM 설치 후에 이 작업을 수행하므로, 대부분의 소스 파일 변경 시
# 빠른 빌드가 가능합니다.
COPY --chown=myuser . ./


# 이미지를 실행합니다.
CMD npm start --silent

이 예제는 Playwright용입니다. Puppeteer를 사용하려면 두 FROM 선언에서 playwright를 puppeteer로 바꾸기만 하면 됩니다.

# 기본 Docker 이미지를 지정합니다. 사용 가능한 이미지에 대한
# 자세한 내용은 https://crawlee.dev/docs/guides/docker-images 에서
# 확인할 수 있습니다. Docker Hub의 다른 이미지도 사용할 수 있습니다.
FROM apify/actor-node-playwright-chrome:20 AS builder

# Docker 레이어 캐시를 활용하여 빌드 속도를 높이기 위해
# package.json과 package-lock.json만 복사합니다.
COPY --chown=myuser package*.json ./

# 모든 의존성을 설치합니다. 설치 속도를 높이기 위해 감사는 건너뜁니다.
RUN npm install --include=dev --audit=false

# 기본 이미지에 설정된 사용자로
# 소스 파일을 복사합니다.
COPY --chown=myuser . ./

# 모든 의존성을 설치하고 프로젝트를 빌드합니다.
# 설치 속도를 높이기 위해 감사는 건너뜁니다.
RUN npm run build

# 최종 이미지 생성
FROM apify/actor-node-playwright-chrome:20

# builder 이미지에서 빌드된 JS 파일만 복사
COPY --from=builder --chown=myuser /home/myuser/dist ./dist

# Docker 레이어 캐시를 활용하여 빌드 속도를 높이기 위해
# package.json과 package-lock.json만 복사합니다.
COPY --chown=myuser package*.json ./

# NPM 패키지를 설치하되, 이미지 크기를 작게 유지하기 위해
# 선택적 의존성과 개발 의존성은 제외합니다. 로그는 최소화하고
# 디버깅을 위해 의존성 트리를 출력합니다.
RUN npm --quiet set progress=false \
    && npm install --omit=dev --omit=optional \
    && echo "설치된 NPM 패키지:" \
    && (npm list --omit=dev --all || true) \
    && echo "Node.js 버전:" \
    && node --version \
    && echo "NPM 버전:" \
    && npm --version

# 마지막으로 나머지 소스 코드 파일과 디렉토리를 복사합니다.
# NPM 설치 후에 이 작업을 수행하므로, 대부분의 소스 파일 변경 시
# 빠른 빌드가 가능합니다.
COPY --chown=myuser . ./

# 이미지를 실행합니다. 헤드리스 브라우저만 사용할 경우
# 약간의 성능 향상을 위해 XVFB 시작 스크립트를 제거할 수 있습니다.
CMD ./start_xvfb_and_run_cmd.sh && npm run start:prod --silent

개요​

버전 관리​

Node.js 버전 관리​

자동화 라이브러리 버전 관리​

프리릴리스 태그​

모범 사례​

이미지 크기에 대한 경고​

Apify Docker 이미지​

actor-node​

actor-node-puppeteer-chrome​

actor-node-playwright​

actor-node-playwright-chrome​

actor-node-playwright-firefox​

actor-node-playwright-webkit​

Dockerfile 예제​

개요