From ac74fdbc2c6d1abaf664890f17d9de18783aa783 Mon Sep 17 00:00:00 2001 From: Vlad Frangu Date: Wed, 20 Aug 2025 21:17:38 +0300 Subject: [PATCH 1/6] docs: upgrades for privilege-less Docker images --- .../development/actor_definition/docker.md | 10 +- .../development/docker_user_updates.mdx | 128 ++++++++++++++++++ 2 files changed, 133 insertions(+), 5 deletions(-) create mode 100644 sources/platform/actors/development/docker_user_updates.mdx diff --git a/sources/platform/actors/development/actor_definition/docker.md b/sources/platform/actors/development/actor_definition/docker.md index ae80ac4a6a..5702b96376 100644 --- a/sources/platform/actors/development/actor_definition/docker.md +++ b/sources/platform/actors/development/actor_definition/docker.md @@ -26,7 +26,7 @@ All Apify Docker images are pre-cached on Apify servers to speed up Actor builds ### 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. +These images come with Node.js (versions `20`, `22`, or `24`) 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 | | ----- | ----------- | @@ -41,7 +41,7 @@ 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. +These images come with Python (version `3.9`, `3.10`, `3.11`, `3.12`, or `3.13`) 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 | | ----- | ----------- | @@ -61,9 +61,9 @@ To use a custom `Dockerfile`, you can either: If no `Dockerfile` is provided, the system uses the following default: ```dockerfile -FROM apify/actor-node:20 +FROM apify/actor-node:24 -COPY package*.json ./ +COPY --chown=myuser:myuser package*.json ./ RUN npm --quiet set progress=false \ && npm install --only=prod --no-optional \ @@ -74,7 +74,7 @@ RUN npm --quiet set progress=false \ && echo "NPM version:" \ && npm --version -COPY . ./ +COPY --chown=myuser:myuser . ./ ``` For more information about `Dockerfile` syntax and commands, see the [Dockerfile reference](https://docs.docker.com/reference/dockerfile/). diff --git a/sources/platform/actors/development/docker_user_updates.mdx b/sources/platform/actors/development/docker_user_updates.mdx new file mode 100644 index 0000000000..c8481c4634 --- /dev/null +++ b/sources/platform/actors/development/docker_user_updates.mdx @@ -0,0 +1,128 @@ +--- +title: Dockerfile user updates +description: Learn what changes you need to do in your Actor Docker files with the new user changes +slug: /actors/development/docker-user-changes +--- + +**Learn what changes and issues you might encounter after some of our Docker images migrate to a privilege-less user** + +--- + +:::danger A note about the warning + +The warning in the base Docker images will be removed near the end of the year! Make sure you update your Docker files until then so you don't forget! + +If you have issues or questions about it, feel free to open an issue on our [GitHub repository](https://github.com/apify/apify-actor-docker/issues/new) + +::: + +--- + +This page is mostly dedicated for the users of the following Docker images: + +- `apify/actor-node` +- `apify/actor-python` +- `apify/actor-python-playwright` +- `apify/actor-python-selenium` + +### What's changed? + +These images are moving from using the built-in **`root`** user and a usually random work directory (for example `/usr/src/app`) to consistent ones with our other Docker images. + +Specifically, the user is now **`myuser`**, and the working directory is **`/home/myuser`**. + +Now, you might ask yourself: why?. Our node Docker images that come with browsers do this in order to ensure the Actor runs in a more-secure environment, should there be any vulnerabilities in the dependencies. + +We want to ensure all our images follow this pattern. As such, after this Pull Request on [GitHub](https://github.com/apify/apify-actor-docker/pull/188), that will become the default for all our Docker images. + +### Common issues + +#### Crawlee images automatically installing `git` in Python images + +If you've built your Actor using [Crawlee](https://crawlee.dev/) templates, you might have the following line in your Dockerfile: + +```dockerfile +RUN apt update && apt install -yq git && rm -rf /var/lib/apt/lists/* +``` + +You can safely remove this line, as the `git` package is now installed in the base image. + +#### `uv` package manager fails to install dependencies + +If you've built your Actor using [Crawlee](https://crawlee.dev/) templates, or you hand-rolled your own Dockerfile, +you might have the following line in your Dockerfile: + +```dockerfile +ENV UV_PROJECT_ENVIRONMENT="/usr/local" +``` + +As of the move to the new user, this variable will cause `uv` to throw an error due to permission errors. You can safely remove it! +Alternatively, you can adjust it to point to the `/home/myuser` directory. + +#### How do I copy my files while also `chown`ing them to the new user? + +When using the `COPY` instruction to copy your files to the container, you should append the `--chown=myuser:myuser` flag to the command. + +Here's a few common example: + +```dockerfile +COPY --chown=myuser:myuser requirements.txt ./ + +COPY --chown=myuser:myuser . ./ +``` + +:::warning + +If your Dockerfile contains a `RUN` instruction similar to the following one, you should remove it: + +```dockerfile +RUN chown -R myuser:myuser /home/myuser +``` + +Instead, add the `chown` flag to the `COPY` instruction: + +```dockerfile +COPY --chown=myuser:myuser . ./ +``` + +Running `chown` across multiple files will needlessly slow down the build process. + +::: + +#### The template I used is trying to add an `apify` user + +If your Docker file has instructions similar to the following: + +```dockerfile +# Create and run as a non-root user. +RUN adduser -h /home/apify -D apify && \ + chown -R apify:apify ./ +USER apify +``` + +You should remove it, as the new user is now **`myuser`**. Don't forget to update your `COPY` instructions to use the `chown` flag with the `myuser` user. + +```dockerfile +COPY --chown=myuser:myuser . ./ +``` + +#### How do I install dependencies that require root access via `apt` / `apk`? + +The good news is that the **`root`** user is still available in the Docker images. If you must run steps that require root access, here's an example of how you should do it: + +```dockerfile +FROM apify/actor-node:24 + +# Switch to root temporarily to install dependencies +USER root + +RUN apt update \ + && apt install -y + +# Switch back to the non-root user +USER myuser + +# ... +``` + +If your Actor *needs* to run as **`root`** for some reason, just add the `USER root` in your Dockerfile after the `FROM` instruction. But for a majority of Actors, this is not the case. From ac630c21b2869748bf13d529b6616e9935385e5c Mon Sep 17 00:00:00 2001 From: Vlad Frangu Date: Wed, 20 Aug 2025 21:22:38 +0300 Subject: [PATCH 2/6] chore: dont need mdx --- .../{docker_user_updates.mdx => docker_user_updates.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename sources/platform/actors/development/{docker_user_updates.mdx => docker_user_updates.md} (100%) diff --git a/sources/platform/actors/development/docker_user_updates.mdx b/sources/platform/actors/development/docker_user_updates.md similarity index 100% rename from sources/platform/actors/development/docker_user_updates.mdx rename to sources/platform/actors/development/docker_user_updates.md From c60e17b5b8537e768638501667c4c413de7b02ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Fri, 22 Aug 2025 00:24:28 +0200 Subject: [PATCH 3/6] remove new page & merge it with existing docker.md fix prose for clarity & conciseness change admonition title remove time anchor change headings --- .../development/actor_definition/docker.md | 106 +++++++++++++++ .../actors/development/docker_user_updates.md | 128 ------------------ 2 files changed, 106 insertions(+), 128 deletions(-) delete mode 100644 sources/platform/actors/development/docker_user_updates.md diff --git a/sources/platform/actors/development/actor_definition/docker.md b/sources/platform/actors/development/actor_definition/docker.md index 5702b96376..8ad6c087f0 100644 --- a/sources/platform/actors/development/actor_definition/docker.md +++ b/sources/platform/actors/development/actor_definition/docker.md @@ -112,3 +112,109 @@ This means the system expects the source code to be in `main.js` by default. If You can check out various optimization tips for Dockerfile in our [Performance](../performance.md) documentation. ::: + +## Updating older Dockerfiles + +Certain Apify base Docker images now use a non-root user to enhance security. This change requires updates to existing Actor `Dockerfile`s that use the `apify/actor-node`, `apify/actor-python`, `apify/actor-python-playwright`, or `apify/actor-python-selenium` images. This section provides guidance on resolving common issues that may arise during this migration. + +:::danger Action required + +The base Docker images display a deprecation warning. This warning will be removed in future versions, so you should update your Dockerfiles to ensure forward compatibility. + +For further assistance, [open an issue in the apify-actor-docker GitHub repository](https://github.com/apify/apify-actor-docker/issues/new). + +::: + +### User and working directory + +To improve security, the affected images no longer run as the `root` user. Instead, they use a dedicated non-root user, `myuser`, and a consistent working directory at `/home/myuser`. This configuration is now the standard for all Apify base Docker images. + +### Common issues + +#### Crawlee templates automatically installing `git` in Python images + +If you've built your Actor using a [Crawlee](https://crawlee.dev/) template, you might have the following line in your `Dockerfile`: + +```dockerfile +RUN apt update && apt install -yq git && rm -rf /var/lib/apt/lists/* +``` + +You can safely remove this line, as the `git` package is now installed in the base image. + +#### `uv` package manager fails to install dependencies + +If you are using the `uv` package manager, you might have the following line in your `Dockerfile`: + +```dockerfile +ENV UV_PROJECT_ENVIRONMENT="/usr/local" +``` + +With the move to a non-root user, this variable will cause `uv` to throw a permission error. You can safely remove this line or adjust it to point to the `/home/myuser` directory. + +#### Copying files with the correct permissions + +When using the `COPY` instruction to copy your files to the container, you should append the `--chown=myuser:myuser` flag to the command to ensure the `myuser` user owns the files. + +Here are a few common examples: + +```dockerfile +COPY --chown=myuser:myuser requirements.txt ./ + +COPY --chown=myuser:myuser . ./ +``` + +:::warning + +If your `Dockerfile` contains a `RUN` instruction similar to the following one, you should remove it: + +```dockerfile +RUN chown -R myuser:myuser /home/myuser +``` + +Instead, add the `--chown` flag to the `COPY` instruction: + +```dockerfile +COPY --chown=myuser:myuser . ./ +``` + +Running `chown` across multiple files needlessly slows down the build process. Using the flag on `COPY` is much more efficient. + +::: + +#### An `apify` user is being added by a template + +If your `Dockerfile` has instructions similar to the following, they were likely added by an older template: + +```dockerfile +# Create and run as a non-root user. +RUN adduser -h /home/apify -D apify && \ + chown -R apify:apify ./ +USER apify +``` + +You should remove these lines, as the new user is now `myuser`. Don't forget to update your `COPY` instructions to use the `--chown` flag with the `myuser` user. + +```dockerfile +COPY --chown=myuser:myuser . ./ +``` + +#### Installing dependencies that require root access + +The `root` user is still available in the Docker images. If you must run steps that require root access (like installing system packages with `apt` or `apk`), you can temporarily switch to the `root` user. + +```dockerfile +FROM apify/actor-node:24 + +# Switch to root temporarily to install dependencies +USER root + +RUN apt update \ + && apt install -y + +# Switch back to the non-root user +USER myuser + +# ... your other instructions +``` + +If your Actor needs to run as `root` for a specific reason, you can add the `USER root` instruction after `FROM`. However, for a majority of Actors, this is not necessary. \ No newline at end of file diff --git a/sources/platform/actors/development/docker_user_updates.md b/sources/platform/actors/development/docker_user_updates.md deleted file mode 100644 index c8481c4634..0000000000 --- a/sources/platform/actors/development/docker_user_updates.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: Dockerfile user updates -description: Learn what changes you need to do in your Actor Docker files with the new user changes -slug: /actors/development/docker-user-changes ---- - -**Learn what changes and issues you might encounter after some of our Docker images migrate to a privilege-less user** - ---- - -:::danger A note about the warning - -The warning in the base Docker images will be removed near the end of the year! Make sure you update your Docker files until then so you don't forget! - -If you have issues or questions about it, feel free to open an issue on our [GitHub repository](https://github.com/apify/apify-actor-docker/issues/new) - -::: - ---- - -This page is mostly dedicated for the users of the following Docker images: - -- `apify/actor-node` -- `apify/actor-python` -- `apify/actor-python-playwright` -- `apify/actor-python-selenium` - -### What's changed? - -These images are moving from using the built-in **`root`** user and a usually random work directory (for example `/usr/src/app`) to consistent ones with our other Docker images. - -Specifically, the user is now **`myuser`**, and the working directory is **`/home/myuser`**. - -Now, you might ask yourself: why?. Our node Docker images that come with browsers do this in order to ensure the Actor runs in a more-secure environment, should there be any vulnerabilities in the dependencies. - -We want to ensure all our images follow this pattern. As such, after this Pull Request on [GitHub](https://github.com/apify/apify-actor-docker/pull/188), that will become the default for all our Docker images. - -### Common issues - -#### Crawlee images automatically installing `git` in Python images - -If you've built your Actor using [Crawlee](https://crawlee.dev/) templates, you might have the following line in your Dockerfile: - -```dockerfile -RUN apt update && apt install -yq git && rm -rf /var/lib/apt/lists/* -``` - -You can safely remove this line, as the `git` package is now installed in the base image. - -#### `uv` package manager fails to install dependencies - -If you've built your Actor using [Crawlee](https://crawlee.dev/) templates, or you hand-rolled your own Dockerfile, -you might have the following line in your Dockerfile: - -```dockerfile -ENV UV_PROJECT_ENVIRONMENT="/usr/local" -``` - -As of the move to the new user, this variable will cause `uv` to throw an error due to permission errors. You can safely remove it! -Alternatively, you can adjust it to point to the `/home/myuser` directory. - -#### How do I copy my files while also `chown`ing them to the new user? - -When using the `COPY` instruction to copy your files to the container, you should append the `--chown=myuser:myuser` flag to the command. - -Here's a few common example: - -```dockerfile -COPY --chown=myuser:myuser requirements.txt ./ - -COPY --chown=myuser:myuser . ./ -``` - -:::warning - -If your Dockerfile contains a `RUN` instruction similar to the following one, you should remove it: - -```dockerfile -RUN chown -R myuser:myuser /home/myuser -``` - -Instead, add the `chown` flag to the `COPY` instruction: - -```dockerfile -COPY --chown=myuser:myuser . ./ -``` - -Running `chown` across multiple files will needlessly slow down the build process. - -::: - -#### The template I used is trying to add an `apify` user - -If your Docker file has instructions similar to the following: - -```dockerfile -# Create and run as a non-root user. -RUN adduser -h /home/apify -D apify && \ - chown -R apify:apify ./ -USER apify -``` - -You should remove it, as the new user is now **`myuser`**. Don't forget to update your `COPY` instructions to use the `chown` flag with the `myuser` user. - -```dockerfile -COPY --chown=myuser:myuser . ./ -``` - -#### How do I install dependencies that require root access via `apt` / `apk`? - -The good news is that the **`root`** user is still available in the Docker images. If you must run steps that require root access, here's an example of how you should do it: - -```dockerfile -FROM apify/actor-node:24 - -# Switch to root temporarily to install dependencies -USER root - -RUN apt update \ - && apt install -y - -# Switch back to the non-root user -USER myuser - -# ... -``` - -If your Actor *needs* to run as **`root`** for some reason, just add the `USER root` in your Dockerfile after the `FROM` instruction. But for a majority of Actors, this is not the case. From de6bb500ffb7ba47aae8eb3f5d5b8d2d3a279f16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Fri, 22 Aug 2025 00:27:56 +0200 Subject: [PATCH 4/6] fix lint --- sources/platform/actors/development/actor_definition/docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/platform/actors/development/actor_definition/docker.md b/sources/platform/actors/development/actor_definition/docker.md index 8ad6c087f0..e4cfe4d1f8 100644 --- a/sources/platform/actors/development/actor_definition/docker.md +++ b/sources/platform/actors/development/actor_definition/docker.md @@ -217,4 +217,4 @@ USER myuser # ... your other instructions ``` -If your Actor needs to run as `root` for a specific reason, you can add the `USER root` instruction after `FROM`. However, for a majority of Actors, this is not necessary. \ No newline at end of file +If your Actor needs to run as `root` for a specific reason, you can add the `USER root` instruction after `FROM`. However, for a majority of Actors, this is not necessary. From 835df6f6411dd3867bc86cefa2315d6cf1694331 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Fri, 22 Aug 2025 12:15:25 +0200 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Vlad Frangu --- .../platform/actors/development/actor_definition/docker.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sources/platform/actors/development/actor_definition/docker.md b/sources/platform/actors/development/actor_definition/docker.md index e4cfe4d1f8..7fc6046121 100644 --- a/sources/platform/actors/development/actor_definition/docker.md +++ b/sources/platform/actors/development/actor_definition/docker.md @@ -115,7 +115,7 @@ You can check out various optimization tips for Dockerfile in our [Performance]( ## Updating older Dockerfiles -Certain Apify base Docker images now use a non-root user to enhance security. This change requires updates to existing Actor `Dockerfile`s that use the `apify/actor-node`, `apify/actor-python`, `apify/actor-python-playwright`, or `apify/actor-python-selenium` images. This section provides guidance on resolving common issues that may arise during this migration. +All Apify base Docker images now use a non-root user to enhance security. This change requires updates to existing Actor `Dockerfile`s that use the `apify/actor-node`, `apify/actor-python`, `apify/actor-python-playwright`, or `apify/actor-python-selenium` images. This section provides guidance on resolving common issues that may arise during this migration. :::danger Action required @@ -149,7 +149,7 @@ If you are using the `uv` package manager, you might have the following line in ENV UV_PROJECT_ENVIRONMENT="/usr/local" ``` -With the move to a non-root user, this variable will cause `uv` to throw a permission error. You can safely remove this line or adjust it to point to the `/home/myuser` directory. +With the move to a non-root user, this variable will cause `uv` to throw a permission error. You can safely remove this line, or, if you need it set to a custom path, adjust it to point to a location in the `/home/myuser` directory. #### Copying files with the correct permissions From 616cc208111bd47f59af8994cea26d266ac76225 Mon Sep 17 00:00:00 2001 From: Vlad Frangu Date: Mon, 25 Aug 2025 09:16:42 +0300 Subject: [PATCH 6/6] chore: admonition changes --- .../platform/actors/development/actor_definition/docker.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sources/platform/actors/development/actor_definition/docker.md b/sources/platform/actors/development/actor_definition/docker.md index 7fc6046121..c3ccc6a776 100644 --- a/sources/platform/actors/development/actor_definition/docker.md +++ b/sources/platform/actors/development/actor_definition/docker.md @@ -117,11 +117,11 @@ You can check out various optimization tips for Dockerfile in our [Performance]( All Apify base Docker images now use a non-root user to enhance security. This change requires updates to existing Actor `Dockerfile`s that use the `apify/actor-node`, `apify/actor-python`, `apify/actor-python-playwright`, or `apify/actor-python-selenium` images. This section provides guidance on resolving common issues that may arise during this migration. -:::danger Action required +If you encounter an issue that is not listed here, or need more guidance on how to update your Dockerfile, please [open an issue in the apify-actor-docker GitHub repository](https://github.com/apify/apify-actor-docker/issues/new). -The base Docker images display a deprecation warning. This warning will be removed in future versions, so you should update your Dockerfiles to ensure forward compatibility. +:::danger Action required -For further assistance, [open an issue in the apify-actor-docker GitHub repository](https://github.com/apify/apify-actor-docker/issues/new). +As of **August 25, 2025** the base Docker images display a deprecation warning that links you here. This warning will be removed start of **February 2026**, so you should update your Dockerfiles to ensure forward compatibility. :::