docs: add binary_state.json permission denied known problem

[MikeMcC399]

• partially resolves issue Describe and demonstrate base and browsers non-root usages #1272
• possibly also related to issue cypress docker image root user misconfiguration #914

Issue

If a custom Docker image is built from cypress/base or cypress/browsers and a Cypress binary is installed (for instance with npx cypress install) and the custom image is then run with a non-root user, Cypress will fail to run with an error message:

Error: EACCES: permission denied, open '/root/.cache/Cypress/<Cypress version>/binary_state.json'

This is due to an open Cypress issue cypress-io/cypress#30684 where Cypress fails to verify the installed Cypress binary if it does not have write access to the Cypress binary directory.

Repro steps

Follow the steps in cypress/base README > Docker build and run, running the generated image with --user node for the non-root user node:

Dockerfile:

FROM cypress/base
COPY . /opt/app
WORKDIR /opt/app
RUN npx cypress install # Install Cypress binary into image

cd examples/basic         # Use a pre-configured simple Cypress E2E project
npm ci                    # Install Cypress
docker build . -f Dockerfile.base -t test-base  # Build a new image
docker run -it --rm --entrypoint bash --user node test-base -c "npx cypress run" # Run Cypress test in container

Change

Add a new topic to the README > Known problems section, referring to Cypress issue cypress-io/cypress#30684.

Suggest the workarounds:

1. Add the RUN command chmod -R 777 /root/.cache/Cypress to the Dockerfile, similar to the workaround employed in factory/installScripts/cypress/default.sh OR
2. Add the ENV environment variable CYPRESS_SKIP_VERIFY=true to the Dockerfile (see Advanced Installation > Environment variables) OR
3. Use the environment variable in the docker run --env CYPRESS_SKIP_VERIFY=true command

Dockerfiles

Dockerfile.base.workaround_1:

FROM cypress/base
COPY . /opt/app
WORKDIR /opt/app
RUN npx cypress install # Install Cypress binary into image
RUN chmod -R 777 /root/.cache/Cypress

Dockerfile.base.workaround_2:

FROM cypress/base
COPY . /opt/app
WORKDIR /opt/app
RUN npx cypress install # Install Cypress binary into image
ENV CYPRESS_SKIP_VERIFY=true

Verification

Ignore warning:

This folder is not writable: /opt/app

Option 1

cd examples/basic         # Use a pre-configured simple Cypress E2E project
npm ci                    # Install Cypress
docker build -f Dockerfile.base.workaround_1 -t test-base-wa1 .
docker run -it --rm --entrypoint bash --user node test-base-wa1 -c "npx cypress run" # Run Cypress test in container

Option 2

cd examples/basic         # Use a pre-configured simple Cypress E2E project
npm ci                    # Install Cypress
docker build -f Dockerfile.base.workaround_2 -t test-base-wa2 .
docker run -it --rm --entrypoint bash --user node test-base-wa2 -c "npx cypress run" # Run Cypress test in container

Option 3

cd examples/basic         # Use a pre-configured simple Cypress E2E project
npm ci                    # Install Cypress
docker build -f Dockerfile.base -t test-base .
docker run -it --rm --entrypoint bash --env CYPRESS_SKIP_VERIFY=true --user node test-base -c "npx cypress run" # Run Cypress test in container

[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.

[jennifer-shehane]

Thanks for the thorough explanation!