docs: add mitigation instructions non-root user not node

[MikeMcC399]

• closes SIGTRAP "Fontconfig error: No writable cache directories" with non-root user not node (1000) #1275

Issue

If a Cypress Docker image is run with a non-root user other than the configured node (1000) user, and if no additional measures are taken, multiple subsystems which rely on being able write into the Linux $HOME directory are unable to cache intermediate results. This causes Cypress to fail to run. The error message contains the text:

Fontconfig error: No writable cache directories
The Test Runner unexpectedly exited via a exit event with signal SIGTRAP

Cypress Docker images (cypress/base, cypress/browsers, cypress/included & custom images generated from cypress/factory) include only a home directory for the non-root user node (1000). This directory is owned by the user node and does not allow other users write access.

Executing npx cypress run with user node or 1000 sets $HOME to /home/node and creates the following directories in the $HOME directory:

.cache/fontconfig
.config/Cypress
.npm/_logs
.pki

Executing npx cypress run with any other non-root user such as 1001 sets $HOME to /, which is owned by root:root with no write access given to any non-root user. This blocks the above directories from being created, which in turn causes Cypress to fail. The failure shown in the issue reproduction for #1275 relates to the failure to create the directory .cache/fontconfig. Other users have reported other error messages, which stem from the same root cause of not be able to write to the directory specified by $HOME.

Mitigation

• Setting the $HOME environment variable to point to the existing /home/node directory and allowing write access to all users mitigates the issue. The workaround described in EACCES permission denied binary_state.json for cypress/base & cypress/browsers which involves allowing write access to all users to /root/.cache/Cypress can be combined for all images for simplicity of description.

Change

Add a new topic to the README > Known problems section.

Suggest the workaround to add the following instructions to the Dockerfile when building a Cypress Docker image to be used with a non-root user other than the built-in node (1000) user:

ENV HOME=/home/node
RUN chmod -R 777 $HOME /root/.cache/Cypress

Verification

Ignore warning:

This folder is not writable: /opt/app

cypress/base

Create examples/basic/Dockerfile.base.workaround_font with the following contents:

FROM cypress/base
COPY . /opt/app
WORKDIR /opt/app
RUN npx cypress install
ENV HOME=/home/node
RUN chmod -R 777 $HOME /root/.cache/Cypress

and execute the following:

cd examples/basic
npm ci
docker build -f Dockerfile.base.workaround_font -t test-base-font .
docker run -it --rm --entrypoint bash --user 1001 test-base-font -c "npx cypress run"

cypress/browsers

Create examples/basic/Dockerfile.browsers.workaround_font with the following contents:

FROM cypress/browsers
COPY . /opt/app
WORKDIR /opt/app
RUN npx cypress install
ENV HOME=/home/node
RUN chmod -R 777 $HOME /root/.cache/Cypress

and execute the following:

cd examples/basic
npm ci
docker build -f Dockerfile.browsers.workaround_font -t test-browsers-font .
docker run -it --rm --entrypoint bash --user 1001 test-browsers-font -c "npx cypress run"

cypress/factory

Create examples/basic-mini/Dockerfile.factory.workaround_font with the following contents:

ARG CHROME_VERSION='125.0.6422.141-1'
ARG EDGE_VERSION='125.0.2535.85-1'
ARG FIREFOX_VERSION='126.0.1'

FROM cypress/factory

COPY . /opt/app
WORKDIR /opt/app
RUN npm install cypress --save-dev
RUN npx cypress install
ENV HOME=/home/node
RUN chmod -R 777 $HOME /root/.cache/Cypress

and execute the following:

cd examples/basic-mini
npm ci
docker build -f Dockerfile.factory.workaround_font -t test-factory-font .
docker run -it --rm --entrypoint bash --user 1001 test-factory-font -c "npx cypress run"

cypress/included

Create examples/included-as-non-root/Dockerfile.included.workaround_font with the following contents:

FROM cypress/included
COPY . /opt/app
WORKDIR /opt/app
ENV HOME=/home/node
RUN chmod -R 777 $HOME

and execute the following:

cd examples/included-as-non-root
npm ci
docker build -f Dockerfile.included.workaround_font -t test-included-font .
docker run -it --rm --entrypoint bash --user 1001 test-browsers-font -c "npx cypress run"

[cypress-app-bot]

• Create a Draft Pull Request if your PR is not ready for review. Mark the PR as Ready for Review when you're ready for a Cypress team member to review the PR.