docs(docker): add image tag naming convention and version pinning gui… (#2185)

See https://apify.slack.com/archives/CQ96RHG2U/p1768757339018769

- 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

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Updates `docker.md` with guidance to improve reproducibility and
clarity around base images.
> 
> - **Image tag naming convention** for Node.js and Python images,
including `{runtime-version}-{library-version}` tags with examples
> - **Finding available tags** via Docker Hub links and a curl/jq
snippet
> - **Version pinning recommendations**: pin Node/Python and
Playwright/Puppeteer/Selenium versions; Dockerfile and `package.json`
examples provided
> - *Warning* on mismatched versions triggering extra downloads and
incompatibilities; notes that using `*` is legacy and pinning is
preferred
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
11df06f. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Author: 3 people

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}` - 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:
+
+| 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}` - A Python version only (e.g., `3.11`, `3.12`, `3.13`)
+- `{python-version}-{library-version}` - A Python version with pinned Playwright/Selenium version
+
+### Available tags
+
+To see all available tags for an image, visit Docker Hub:
+
+- [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:
+
+```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, 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:
+
+```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 (alternative 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
+1. Predictability - You know exactly which version you're running
+1. Debugging - Version-specific issues are easier to track down
+
 ## 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.