From 11df06fec1560200aafd518ffb0697f069c160f2 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 18 Jan 2026 17:36:42 +0000 Subject: [PATCH 1/2] docs(docker): add image tag naming convention and version pinning guidance - Added section explaining Docker image tag naming convention (e.g., `22-1.52.0` for Node.js 22 with Playwright 1.52.0) - Added direct links to Docker Hub tags pages for discovering available versions - Added guidance on pinning Playwright/Puppeteer versions for reproducible builds - Clarified that using `*` as version is a legacy approach, with pinning now preferred --- .../development/actor_definition/docker.md | 95 +++++++++++++++++++ 1 file changed, 95 insertions(+) diff --git a/sources/platform/actors/development/actor_definition/docker.md b/sources/platform/actors/development/actor_definition/docker.md index 734540c7a1..a79e8abd1d 100644 --- a/sources/platform/actors/development/actor_definition/docker.md +++ b/sources/platform/actors/development/actor_definition/docker.md @@ -49,6 +49,101 @@ These images come with Python (version `3.9`, `3.10`, `3.11`, `3.12`, or `3.13`) | [`actor-python-playwright`](https://hub.docker.com/r/apify/actor-python-playwright) | Debian image with [`playwright`](https://github.com/microsoft/playwright) and all its browsers. | | [`actor-python-selenium`](https://hub.docker.com/r/apify/actor-python-selenium) | Debian image with [`selenium`](https://github.com/seleniumhq/selenium), Google Chrome, and [ChromeDriver](https://developer.chrome.com/docs/chromedriver/). | +## Image tag naming convention + +Docker image tags follow a consistent naming pattern that allows you to pin specific versions: + +### Node.js images + +For Node.js images, the tag format is: + +- `{node-version}` - Node.js version only (e.g., `20`, `22`, `24`) +- `{node-version}-{library-version}` - Node.js version with pinned Playwright/Puppeteer version (e.g., `22-1.52.0`) + +**Examples:** + +| Tag | Description | +| --- | ----------- | +| `20` | Node.js 20 with the Playwright/Puppeteer version that was latest when the image was built | +| `22` | Node.js 22 with the Playwright/Puppeteer version that was latest when the image was built | +| `22-1.52.0` | Node.js 22 with Playwright/Puppeteer version 1.52.0 pinned | +| `latest` | Latest LTS Node.js version | + +### Python images + +For Python images, the tag format is: + +- `{python-version}` - Python version only (e.g., `3.11`, `3.12`, `3.13`) +- `{python-version}-{library-version}` - Python version with pinned Playwright/Selenium version + +### Finding available tags + +To see all available tags for an image, visit the Docker Hub tags page: + +- [actor-node-playwright-chrome tags](https://hub.docker.com/r/apify/actor-node-playwright-chrome/tags) +- [actor-node-playwright tags](https://hub.docker.com/r/apify/actor-node-playwright/tags) +- [actor-node-puppeteer-chrome tags](https://hub.docker.com/r/apify/actor-node-puppeteer-chrome/tags) +- [actor-python-playwright tags](https://hub.docker.com/r/apify/actor-python-playwright/tags) + +You can also query available tags programmatically: + +```bash +curl -s "https://registry.hub.docker.com/v2/repositories/apify/actor-node-playwright-chrome/tags?page_size=50" | jq '.results[].name' +``` + +## Version pinning for reproducible builds + +For production Actors, we recommend pinning both the Node.js/Python version and the browser automation library version in your Dockerfile. This ensures reproducible builds and prevents unexpected behavior when new versions are released. + +### Recommended approach + +**In your Dockerfile**, use a fully pinned tag: + +```dockerfile +# Pin both Node.js 22 and Playwright 1.52.0 +FROM apify/actor-node-playwright-chrome:22-1.52.0 +``` + +**In your `package.json`**, match the Playwright/Puppeteer version to your Docker image tag: + +```json +{ + "dependencies": { + "apify": "^3.5.0", + "@crawlee/playwright": "^3.15.0", + "playwright": "1.52.0" + } +} +``` + +:::warning Why version matching matters + +When the Playwright/Puppeteer version in your `package.json` differs from what's pre-installed in the Docker image, npm will download and install the version specified in `package.json`. This can lead to: + +- Slower builds due to downloading browser binaries +- Potential version incompatibilities +- Inconsistent behavior between local development and production + +::: + +### Using `*` as version (legacy approach) + +You may encounter older documentation or templates using `*` as the Playwright/Puppeteer version: + +```json +{ + "dependencies": { + "playwright": "*" + } +} +``` + +The asterisk (`*`) tells npm to use whatever version is already installed, which prevents re-downloading the library. While this approach still works, **pinning specific versions is now preferred** because: + +1. **Reproducibility** - Your builds will behave the same way regardless of when you build them +2. **Predictability** - You know exactly which version you're running +3. **Debugging** - Easier to track down version-specific issues + ## Custom Dockerfile Apify uses Docker to build and run Actors. If you create an Actor from a template, it already contains an optimized `Dockerfile` for the given use case. From 1020ed2be0f924a1fc474f6330a6c35484c72300 Mon Sep 17 00:00:00 2001 From: Ondra Urban <23726914+mnmkng@users.noreply.github.com> Date: Wed, 21 Jan 2026 21:16:02 +0100 Subject: [PATCH 2/2] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Thanks for the fixes! Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com> --- .../development/actor_definition/docker.md | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/sources/platform/actors/development/actor_definition/docker.md b/sources/platform/actors/development/actor_definition/docker.md index a79e8abd1d..9b604a88ac 100644 --- a/sources/platform/actors/development/actor_definition/docker.md +++ b/sources/platform/actors/development/actor_definition/docker.md @@ -57,10 +57,10 @@ Docker image tags follow a consistent naming pattern that allows you to pin spec For Node.js images, the tag format is: -- `{node-version}` - Node.js version only (e.g., `20`, `22`, `24`) -- `{node-version}-{library-version}` - Node.js version with pinned Playwright/Puppeteer version (e.g., `22-1.52.0`) +- `{node-version}` - A Node.js version only (e.g., `20`, `22`, `24`) +- `{node-version}-{library-version}` - A Node.js version with pinned Playwright/Puppeteer version (e.g., `22-1.52.0`) -**Examples:** +Examples: | Tag | Description | | --- | ----------- | @@ -73,17 +73,17 @@ For Node.js images, the tag format is: For Python images, the tag format is: -- `{python-version}` - Python version only (e.g., `3.11`, `3.12`, `3.13`) -- `{python-version}-{library-version}` - Python version with pinned Playwright/Selenium version +- `{python-version}` - A Python version only (e.g., `3.11`, `3.12`, `3.13`) +- `{python-version}-{library-version}` - A Python version with pinned Playwright/Selenium version -### Finding available tags +### Available tags -To see all available tags for an image, visit the Docker Hub tags page: +To see all available tags for an image, visit Docker Hub: -- [actor-node-playwright-chrome tags](https://hub.docker.com/r/apify/actor-node-playwright-chrome/tags) -- [actor-node-playwright tags](https://hub.docker.com/r/apify/actor-node-playwright/tags) -- [actor-node-puppeteer-chrome tags](https://hub.docker.com/r/apify/actor-node-puppeteer-chrome/tags) -- [actor-python-playwright tags](https://hub.docker.com/r/apify/actor-python-playwright/tags) +- [View actor-node-playwright-chrome tags](https://hub.docker.com/r/apify/actor-node-playwright-chrome/tags) +- [View actor-node-playwright tags](https://hub.docker.com/r/apify/actor-node-playwright/tags) +- [View actor-node-puppeteer-chrome tags](https://hub.docker.com/r/apify/actor-node-puppeteer-chrome/tags) +- [View actor-python-playwright tags](https://hub.docker.com/r/apify/actor-python-playwright/tags) You can also query available tags programmatically: @@ -93,18 +93,18 @@ curl -s "https://registry.hub.docker.com/v2/repositories/apify/actor-node-playwr ## Version pinning for reproducible builds -For production Actors, we recommend pinning both the Node.js/Python version and the browser automation library version in your Dockerfile. This ensures reproducible builds and prevents unexpected behavior when new versions are released. +For production Actors, pin both the Node.js/Python version and the browser automation library version in your Dockerfile. This ensures reproducible builds and prevents unexpected behavior when new versions are released. ### Recommended approach -**In your Dockerfile**, use a fully pinned tag: +In your `Dockerfile`, use a fully pinned tag: ```dockerfile # Pin both Node.js 22 and Playwright 1.52.0 FROM apify/actor-node-playwright-chrome:22-1.52.0 ``` -**In your `package.json`**, match the Playwright/Puppeteer version to your Docker image tag: +In your `package.json`, match the Playwright/Puppeteer version to your Docker image tag: ```json { @@ -126,7 +126,7 @@ When the Playwright/Puppeteer version in your `package.json` differs from what's ::: -### Using `*` as version (legacy approach) +### Using `*` as version (alternative approach) You may encounter older documentation or templates using `*` as the Playwright/Puppeteer version: @@ -140,9 +140,9 @@ You may encounter older documentation or templates using `*` as the Playwright/P The asterisk (`*`) tells npm to use whatever version is already installed, which prevents re-downloading the library. While this approach still works, **pinning specific versions is now preferred** because: -1. **Reproducibility** - Your builds will behave the same way regardless of when you build them -2. **Predictability** - You know exactly which version you're running -3. **Debugging** - Easier to track down version-specific issues +1. Reproducibility - Your builds will behave the same way regardless of when you build them +1. Predictability - You know exactly which version you're running +1. Debugging - Version-specific issues are easier to track down ## Custom Dockerfile