docs: Dockerfile doc improvements & rewrites (#1031)

Ensure style guide compliance
add new versions
provide cross-references to other part of documentation
Add admonitions
rewrites for readability and clarity

Author: TC-MO

sources/platform/actors/development/actor_definition/actor_json.md

@@ -69,7 +69,7 @@ Actor `name`, `version`, `buildTag`, and `environmentVariables` are currently on
 | `version` | Required | The version of the Actor, specified in the format `[Number].[Number]`, e.g., `0.1`, `0.3`, `1.0`, `1.3`, etc. |
 | `buildTag` | Optional | The tag name to be applied to a successful build of the Actor. If not specified, defaults to `latest`. Refer to the [builds](../builds_and_runs/builds.md) for more information. |
 | `environmentVariables` | Optional | A map of environment variables to be used during local development. These variables will also be applied to the Actor when deployed on the Apify platform. For more details, see the [environment variables](/cli/docs/vars) section of Apify CLI documentation. |
-| `dockerfile` | Optional | The path to the Dockerfile to be used for building the Actor on the platform. If not specified, the system will search for Dockerfiles in the `.actor/Dockerfile` and `Dockerfile` paths, in that order. Refer to the [Dockerfile](./dockerfile.md) section for more information. |
+| `dockerfile` | Optional | The path to the Dockerfile to be used for building the Actor on the platform. If not specified, the system will search for Dockerfiles in the `.actor/Dockerfile` and `Dockerfile` paths, in that order. Refer to the [Dockerfile](./docker.md) section for more information. |
 | `dockerContextDir` | Optional | The path to the directory to be used as the Docker context when building the Actor. The path is relative to the location of the `actor.json` file. This property is useful for monorepos containing multiple Actors. Refer to the [Actor monorepos](../deployment/source_types.md#actor-monorepos) section for more details. |
 | `readme` | Optional | The path to the README file to be used on the platform. If not specified, the system will look for README files in the `.actor/README.md` and `README.md` paths, in that order of preference. Check out [Apify Academy article on writing a quality README files](/academy/get-most-of-actors/actor-readme) guidance. |
 | `input` | Optional | You can embed your [input schema](./input_schema/index.md) object directly in `actor.json` under the `input` field. You can also provide a path to a custom input schema. If not provided, the input schema at `.actor/INPUT_SCHEMA.json` or `INPUT_SCHEMA.json` is used, in this order of preference. |

sources/platform/actors/development/actor_definition/docker.md

@@ -0,0 +1,108 @@
+---
+title: Dockerfile
+description: Learn about the available Docker images you can use as a base for your Apify Actors. Choose the right base image based on your Actor's requirements and the programming language you're using.
+slug: /actors/development/actor-definition/dockerfile
+sidebar_position: 4
+---
+
+**Learn about the available Docker images you can use as a base for your Apify Actors. Choose the right base image based on your Actor's requirements and the programming language you're using.**
+
+---
+
+When developing an [Actor](/sources/platform/actors/index.mdx) on the Apify platform, you can choose from a variety of pre-built Docker iamges to serve as the base for your Actor. These base images come with pre-installed dependencies and tools, making it easier to set up your development envrionment and ensuring consistent behavior across different environments.
+
+## Base Docker images
+
+Apify provides several Docker images that can serve as base images for Actors. All images come in two versions:
+
+- `latest` - This version represents the stable and production-ready release of the base image.
+- `beta` - This version is intended for testing new features. Use at your own risk.
+
+:::note Pre-cached Docker images
+
+All Apify Docker images are pre-cached on Apify servers to speed up Actor builds and runs. The source code for generating these images is available in the [apify-actor-docker](https://github.com/apify/apify-actor-docker) repository.
+
+:::
+
+### Node.js base images
+
+These images come with Node.js (versions `16`, `18`, `20`, or `22`) the [Apify SDK for JavaScript](/sdk/js), and [Crawlee](https://crawlee.dev/) preinstalled. The `latest` tag corresponds to the latest LTS version of Node.js.
+
+| Image | Description |
+| ----- | ----------- |
+| [`actor-node`](https://hub.docker.com/r/apify/actor-node/) | Slim Alpine Linux image with only essential tools. Does not include headless browsers. |
+| [`actor-node-puppeteer-chrome`](https://hub.docker.com/r/apify/actor-node-puppeteer-chrome/) | Debian image with Chromium, Google Chrome, and the [`puppeteer`](https://github.com/puppeteer/puppeteer) library. |
+| [`actor-node-playwright-chrome`](https://hub.docker.com/r/apify/actor-node-playwright-chrome/) | Debian image with Chromium, Google Chrome, and the [`playwright`](https://github.com/microsoft/playwright) library. |
+| [`actor-node-playwright-firefox`](https://hub.docker.com/r/apify/actor-node-playwright-firefox/) | Debian image with Firefox and the [`playwright`](https://github.com/microsoft/playwright) library . |
+| [`actor-node-playwright-webkit`](https://hub.docker.com/r/apify/actor-node-playwright-webkit/) | Ubuntu image with WebKit and the [`playwright`](https://github.com/microsoft/playwright) library. |
+| [`actor-node-playwright`](https://hub.docker.com/r/apify/actor-node-playwright/) | Ubuntu image with [`playwright`](https://github.com/microsoft/playwright) and all its browsers (Chromium, Google Chrome, Firefox, WebKit). |
+
+See the [Docker image guide](/sdk/js/docs/guides/docker-images) for more details.
+
+### Python base images
+
+These images come with Python (version `3.8`, `3.9`, `3.10`, `3.11`, or `3.12`) and the [Apify SDK for Python](/sdk/python) preinstalled. The `latest` tag corresponds to the latest Python 3 version supported by the Apify SDK.
+
+| Image | Description |
+| ----- | ----------- |
+| [`actor-python`](https://hub.docker.com/r/apify/actor-python) | Slim Debian image with only the Apify SDK for Python. Does not include headless browsers. |
+| [`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://chromedriver.chromium.org/). |
+
+## 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.
+
+To use a custom `Dockerfile`, you can either:
+
+- Reference it from the `dockerfile` field in `.actor/actor.json`,
+- Store it in `.actor/Dockerfile` or `Dockerfile` in the root directory (searched in this order of preference).
+
+If no `Dockerfile` is provided, the system uses the following default:
+
+```dockerfile
+FROM apify/actor-node:20
+
+COPY package*.json ./
+
+RUN npm --quiet set progress=false \
+ && npm install --only=prod --no-optional \
+ && echo "Installed NPM packages:" \
+ && (npm list --only=prod --no-optional --all || true) \
+ && echo "Node.js version:" \
+ && node --version \
+ && echo "NPM version:" \
+ && npm --version
+
+COPY . ./
+```
+
+For more information about `Dockerfile` syntax and commands, see the [Dockerfile reference](https://docs.docker.com/engine/reference/builder/).
+
+:::note Custom base images
+
+While `apify/actor-node` is a base Docker image provided by Apify, you can use other Docker images as the base for your Actors. <br/>
+However, using the Apify images has some performance advantages, as they are pre-caches on Apify servers.
+
+:::
+
+By default, Apify base Docker images with the Apify SDK and Crawlee start your Node.js application the same way as `npm start`, i.e, by running the command specified in `package.json` under `scripts` - `start`. The default `package.json` is similar to:
+
+```json
+{
+    "description": "Anonymous Actor on the Apify platform",
+    "version": "0.0.1",
+    "license": "UNLICENSED",
+    "main": "main.js",
+    "scripts": {
+        "start": "node main.js"
+    },
+    "dependencies": {
+        "apify": "^3.0.0",
+        "crawlee": "^3.0.0"
+    },
+    "repository": {}
+}
+```
+
+This means the system expects the source code to be in `main.js` by default. If you want to override this behavior, ues a custom `package.json` and/or `Dockerfile`.

sources/platform/actors/development/actor_definition/dockerfile.md

@@ -16,7 +16,7 @@ Basically, Actors are programs packaged as [Docker images](https://hub.docker.co
 Actors have the following elements:
 
 - The main **[actor.json](./actor_json.md)** file contains **metadata** such as the Actor name, description, author, version, and links pointing to the other definition files below.
-- **[Dockerfile](./dockerfile.md)** which specifies where is the Actor's source code, how to build it, and run it.
+- **[Dockerfile](./docker.md)** which specifies where is the Actor's source code, how to build it, and run it.
 - **Documentation** in the form of a **README.md** file.
 - **[Input](./input_schema/index.md)** and **[output schemas](./output_schema.md)** that describe what input the Actor requires and what results it produces.
 - Access to an out-of-box **[storage](../../../storage/index.md)** system for Actor data, results, and files.

sources/platform/actors/development/actor_definition/index.md

@@ -9,17 +9,13 @@ sidebar_position: 4
 
 ---
 
-The structure and placement of an Apify Actor's source code is defined by its [`Dockerfile`](./dockerfile.md). If you create the Actor from one of Apify's [templates](https://apify.com/templates), the source code by default is placed in the `/src`.
+The Apify Actor's source code placement is defined by its [Dockerfile](./docker.md). If you have created the Actor from one of Apify's [templates](https://apify.com/templates) then it's by convention placed in the `/src` directory.
 
 You have the flexibility to choose any programming language, technologies, and dependencies (such as Chrome browser, Selenium, Cypress, or others) for your projects. The only requirement is to define a Dockerfile that builds the image for your Actor, including all dependencies and your source code.
 
 ## Example setup
 
-To better understand how to structure your Actor's source code, let's take a look at an example for a JavaScript Actor.
-
-### `Dockerfile`
-
-Here's the complete `Dockerfile`
+Let's take a look at the example JavaScript Actor's source code. The following Dockerfile:
 
 ```dockerfile
 FROM apify/actor-node:20