You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: improve Docker image version pinning guidance (#3349)
- Update best practices to recommend pinning both Node.js and automation
library versions for reproducible builds
- Add warning about version matching importance between Dockerfile and
package.json
- Document the asterisk `*` approach as an alternative rather than the
primary recommendation
- Add "Finding available tags" section with Docker Hub links and
programmatic query example
Co-authored-by: Claude <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: docs/guides/docker_images.mdx
+47-5Lines changed: 47 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -69,14 +69,37 @@ FROM apify/actor-node-playwright-chrome:20-1.10.0-beta
69
69
70
70
## Best practices
71
71
72
-
- Node.js version tag should **always** be used.
73
-
- The automation library version tag should be used for **added security**.
74
-
- Asterisk `*` should be used as the automation library version in our `package.json` files.
72
+
For production crawlers, we recommend pinning both the Node.js version **and** the automation library version in your Dockerfile tag. This ensures reproducible builds and prevents unexpected behavior when new versions are released.
75
73
76
-
It makes sure the pre-installed version of Puppeteer or Playwright is not re-installed on build. This is important, because those libraries are only guaranteed to work with specific versions of browsers, and those browsers come pre-installed in the image.
74
+
### Recommended approach: Pin both versions
75
+
76
+
Match the automation library version in your `package.json` with the version in your Docker image tag:
77
77
78
78
```dockerfile
79
-
FROM apify/actor-node-playwright-chrome:20
79
+
FROM apify/actor-node-playwright-chrome:22-1.52.0
80
+
```
81
+
82
+
```json
83
+
{
84
+
"dependencies": {
85
+
"crawlee": "^3.0.0",
86
+
"playwright": "1.52.0"
87
+
}
88
+
}
89
+
```
90
+
91
+
:::warning Why version matching matters
92
+
93
+
If you pin the Docker image to `22-1.52.0` but install a different Playwright version via `package.json`, you may encounter browser compatibility issues. The browsers pre-installed in the image are specifically built for that Playwright version.
94
+
95
+
:::
96
+
97
+
### Alternative approach: Using asterisk `*`
98
+
99
+
You can also use asterisk `*` as the automation library version in your `package.json`:
100
+
101
+
```dockerfile
102
+
FROM apify/actor-node-playwright-chrome:22
80
103
```
81
104
82
105
```json
@@ -88,6 +111,25 @@ FROM apify/actor-node-playwright-chrome:20
88
111
}
89
112
```
90
113
114
+
This makes sure the pre-installed version of Puppeteer or Playwright is not re-installed on build. However, this approach is less predictable because you'll get whatever version was latest when the Docker image was built.
115
+
116
+
## Finding available tags
117
+
118
+
To see all available tags for each image, you can visit Docker Hub directly:
Copy file name to clipboardExpand all lines: website/versioned_docs/version-3.15/guides/docker_images.mdx
+47-5Lines changed: 47 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -69,14 +69,37 @@ FROM apify/actor-node-playwright-chrome:20-1.10.0-beta
69
69
70
70
## Best practices
71
71
72
-
- Node.js version tag should **always** be used.
73
-
- The automation library version tag should be used for **added security**.
74
-
- Asterisk `*` should be used as the automation library version in our `package.json` files.
72
+
For production crawlers, we recommend pinning both the Node.js version **and** the automation library version in your Dockerfile tag. This ensures reproducible builds and prevents unexpected behavior when new versions are released.
75
73
76
-
It makes sure the pre-installed version of Puppeteer or Playwright is not re-installed on build. This is important, because those libraries are only guaranteed to work with specific versions of browsers, and those browsers come pre-installed in the image.
74
+
### Recommended approach: Pin both versions
75
+
76
+
Match the automation library version in your `package.json` with the version in your Docker image tag:
77
77
78
78
```dockerfile
79
-
FROM apify/actor-node-playwright-chrome:20
79
+
FROM apify/actor-node-playwright-chrome:22-1.52.0
80
+
```
81
+
82
+
```json
83
+
{
84
+
"dependencies": {
85
+
"crawlee": "^3.0.0",
86
+
"playwright": "1.52.0"
87
+
}
88
+
}
89
+
```
90
+
91
+
:::warning Why version matching matters
92
+
93
+
If you pin the Docker image to `22-1.52.0` but install a different Playwright version via `package.json`, you may encounter browser compatibility issues. The browsers pre-installed in the image are specifically built for that Playwright version.
94
+
95
+
:::
96
+
97
+
### Alternative approach: Using asterisk `*`
98
+
99
+
You can also use asterisk `*` as the automation library version in your `package.json`:
100
+
101
+
```dockerfile
102
+
FROM apify/actor-node-playwright-chrome:22
80
103
```
81
104
82
105
```json
@@ -88,6 +111,25 @@ FROM apify/actor-node-playwright-chrome:20
88
111
}
89
112
```
90
113
114
+
This makes sure the pre-installed version of Puppeteer or Playwright is not re-installed on build. However, this approach is less predictable because you'll get whatever version was latest when the Docker image was built.
115
+
116
+
## Finding available tags
117
+
118
+
To see all available tags for each image, you can visit Docker Hub directly:
0 commit comments