{"id":13711992,"url":"https://github.com/cypress-io/cypress-docker-images","last_synced_at":"2025-05-14T12:10:38.667Z","repository":{"id":37587553,"uuid":"92077390","full_name":"cypress-io/cypress-docker-images","owner":"cypress-io","description":"Docker images with Cypress dependencies and browsers","archived":false,"fork":false,"pushed_at":"2025-05-13T20:44:41.000Z","size":1883,"stargazers_count":1049,"open_issues_count":24,"forks_count":392,"subscribers_count":45,"default_branch":"master","last_synced_at":"2025-05-13T21:45:00.409Z","etag":null,"topics":["cypress","docker","docker-image"],"latest_commit_sha":null,"homepage":"https://on.cypress.io/continuous-integration","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cypress-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-05-22T16:52:05.000Z","updated_at":"2025-05-13T20:44:46.000Z","dependencies_parsed_at":"2023-10-12T07:06:10.529Z","dependency_job_id":"d551ac7d-294c-4889-a678-acfc440f81c9","html_url":"https://github.com/cypress-io/cypress-docker-images","commit_stats":{"total_commits":742,"total_committers":111,"mean_commits":6.684684684684685,"dds":0.6954177897574124,"last_synced_commit":"c61c638bb66902b5194f5d5b1a16485b559a8c01"},"previous_names":["cypress-io/docker"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fcypress-docker-images","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fcypress-docker-images/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fcypress-docker-images/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fcypress-docker-images/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cypress-io","download_url":"https://codeload.github.com/cypress-io/cypress-docker-images/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254140758,"owners_count":22021219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cypress","docker","docker-image"],"created_at":"2024-08-02T23:01:13.751Z","updated_at":"2025-05-14T12:10:38.652Z","avatar_url":"https://github.com/cypress-io.png","language":"Dockerfile","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# Cypress Docker Images [![CircleCI](https://circleci.com/gh/cypress-io/cypress-docker-images/tree/master.svg?style=svg)](https://circleci.com/gh/cypress-io/cypress-docker-images/tree/master)\n\nCypress Docker images are published to [Cypress on Docker Hub](https://hub.docker.com/u/cypress).\n\nThese images provide all of the required dependencies for running Cypress in [Docker](https://docs.docker.com/guides/docker-overview/).\n\nWe build four images: click on the image name to see the available tags with versions, and refer to the [Tags](#tags) section below. These allow you to target specific combinations you need.\n\n| Image Name                                                     | Description                                                                        | Monthly pulls                                                                                                                         |\n| -------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| [cypress/factory](https://hub.docker.com/r/cypress/factory/)   | A base image template which can be used with ARGs to create a custom docker image. | [![Docker Pulls](https://img.shields.io/docker/pulls/cypress/factory.svg?maxAge=604800)](https://hub.docker.com/r/cypress/factory/)   |\n| [cypress/base](https://hub.docker.com/r/cypress/base/)         | All operating system dependencies, no Cypress, and no browsers.                    | [![Docker Pulls](https://img.shields.io/docker/pulls/cypress/base.svg?maxAge=604800)](https://hub.docker.com/r/cypress/base/)         |\n| [cypress/browsers](https://hub.docker.com/r/cypress/browsers/) | All operating system dependencies, no Cypress, and some browsers.                  | [![Docker Pulls](https://img.shields.io/docker/pulls/cypress/browsers.svg?maxAge=604800)](https://hub.docker.com/r/cypress/browsers/) |\n| [cypress/included](https://hub.docker.com/r/cypress/included/) | All operating system dependencies, Cypress, and some browsers installed globally.  | [![Docker Pulls](https://img.shields.io/docker/pulls/cypress/included.svg?maxAge=604800)](https://hub.docker.com/r/cypress/included/) |\n\n## Platforms\n\nCypress Docker images are Linux based, using the Docker image [debian:12-slim](https://hub.docker.com/_/debian) as the default base image. Each of the above listed Cypress Docker images is published with [multi-architecture](https://docs.docker.com/contribute/style/terminology/#multi-architecture--multi-arch) support for `Linux/amd64` and `Linux/arm64` platforms.\n\nCypress Docker images can be run as containers on Continuous Integration (CI) systems which support Docker. Cypress Docker images can also be run locally under [Docker Desktop](https://docs.docker.com/desktop/) for Mac, Linux or Windows environments.\n\nIn the case of Windows environments, see [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/) and Cypress documentation [Windows Subsystem for Linux](https://on.cypress.io/guides/references/advanced-installation#Windows-Subsystem-for-Linux) for additional information regarding Microsoft's `WSL2` and `WSLg` subsystems. The documentation and scripts in this repository assume that Docker Desktop for Windows runs in a virtual Linux environment.\n\n## Browsers\n\nCypress Docker images [cypress/browsers](./browsers/) include browsers for the `Linux/amd64` and the `Linux/arm64` platform according to browser availability as shown in the following table.\n\n| Browser                    |   `Linux/amd64`    | `Linux/arm64`                                                                |\n| -------------------------- | :----------------: | :--------------------------------------------------------------------------- |\n| [Google Chrome][Chrome]    | :white_check_mark: | see [#1188](https://github.com/cypress-io/cypress-docker-images/issues/1188) |\n| [Mozilla Firefox][Firefox] | :white_check_mark: | :white_check_mark:                                                           |\n| [Microsoft Edge][Edge]     | :white_check_mark: | see [#1189](https://github.com/cypress-io/cypress-docker-images/issues/1189) |\n\nOn POSIX-based systems, or with [Git for Windows](https://gitforwindows.org/) at a Git Bash prompt, execute `uname -m` to display your system's architecture. ([x86_64](https://en.wikipedia.org/wiki/X86-64) is equivalent to `amd64`.)\n\n[cypress/included](./included/) images, which are built on top of [cypress/browsers](./browsers/), contain the same set of browsers.\n\n[Tags](#tags) for [cypress/browsers](./browsers/) and [cypress/included](./included/) images show which versions of the browsers are loaded into the respective image.\n\nFor `Linux/arm64` images, the lowest available Firefox version is `136`.\n\nBuilding a custom image with [cypress/factory](./factory/) allows selection of individual browsers from the above list.\n\nCypress officially [supports][Cypress Browser Support] the latest 3 major versions of Chrome, Firefox, and Edge browsers. We recommend using up to date Cypress Docker images for supportability.\n\n\u003c!-- browser links --\u003e\n\n[Chrome]: https://developer.chrome.com/\n[Firefox]: https://www.mozilla.org/firefox\n[Firefox Channel Choice]: https://support.mozilla.org/en-US/kb/choosing-firefox-update-channel\n[Edge]: https://developer.microsoft.com/microsoft-edge/\n[Chromium]: https://www.chromium.org/Home/\n[Cypress Browser Support]: https://docs.cypress.io/app/references/launching-browsers#Browser-versions-supported\n\n### Debian packages\n\n[Debian][Debian packages] provides two Cypress-compatible browsers as packages covering both `amd64` and `arm64` architectures.\nThese can be used to complement the browsers that are configurable through the `cypress/factory` build process:\n\n- See the directory [examples/chromium](./examples/chromium/) to add the current version of Chromium for Debian to Cypress Docker images.\n  The [Debian Chromium Wiki][Debian-Chromium-Wiki] describes the [Chromium][Chromium] browser distribution details.\n  Chromium is not currently included in the `cypress/factory` build process.\n  See [#1191](https://github.com/cypress-io/cypress-docker-images/issues/1191) for progress of this integration.\n\n- See the directory [examples/firefox-esr](./examples/firefox-esr/) to add Firefox ESR for Debian to Cypress Docker images.\n  The [Debian Firefox Wiki][Debian-Firefox-Wiki] describes the [Firefox][Firefox] browser distribution details from the [Extended Support Release][Firefox Channel Choice] channel.\n  This differs from the `cypress/factory` build process which uses Firefox versions from the [Rapid Release][Firefox Channel Choice] channel.\n\n\u003c!-- Debian links --\u003e\n\n[Debian packages]: https://www.debian.org/distrib/packages\n[Debian-Chromium-Wiki]: https://wiki.debian.org/Chromium\n[Debian-Firefox-Wiki]: https://wiki.debian.org/Firefox\n\n## Tags\n\nTo select an image, use the `[REPOSITORY[:TAG]]` format. `REPOSITORY` is one of `cypress/factory`, `cypress/base`, `cypress/browsers` or `cypress/included`. If `TAG` is omitted, it defaults to `latest`.\n\nFor each of the `REPOSITORY` image types, see the `Tags` section of each `README` document for more detail.\n\n| Image Type README                                    | Example Tag |\n| ---------------------------------------------------- | ----------- |\n| [cypress/factory README](./factory/README.md#tags)   | `5.1.0`     |\n| [cypress/base README](./base/README.md#tags)         | `22.11.0`   |\n| [cypress/browsers README](./browsers/README.md#tags) | `22.11.0`   |\n| [cypress/included README](./included/README.md#tags) | `13.16.0`   |\n\nImages with a specific version tag for `cypress/factory` and `cypress/base` (for example: `cypress/factory:5.1.0` and `cypress/base:22.11.0`) are frozen once they have been published. The same is true for images linked to full browser version tags for `cypress/browsers` and `cypress/included` (for example: `cypress/browsers:node-22.11.0-chrome-131.0.6778.69-1-ff-132.0.2-edge-131.0.2903.51-1` and `cypress/included:cypress-13.16.0-node-22.11.0-chrome-131.0.6778.69-1-ff-132.0.2-edge-131.0.2903.51-1`).\n\nThe version tags for Chrome and Edge for `Linux/arm64` images, as well as Firefox version tags below `ff-136.x`, do not carry any meaning due to browser unavailability for this platform.\nWith the tag scheme used by Cypress Docker images, all tags are required to be in place to allow use of Docker's [multi-platform images](https://docs.docker.com/build/building/multi-platform/), irrespective of whether the browser is actually available or not.\n\n`cypress/browsers` and `cypress/included` images are also offered with short-form convenience tags that do not include browser version details (example: `cypress/browsers:22.11.0` and `cypress/included:13.16.0`). The tags that these images refer to can change without notice if browser updates are made.\n\nSimilarly, the convenience tag `latest`, for each of the image types, changes without notice.\n\nTo avoid breaking changes when new images are released, use a corresponding frozen image tag rather than a convenience tag.\n\n## Usage\n\n📍Cypress Docker images are offered as a convenience measure. The goal is to offer Node.js, Browser and Cypress versions to streamline running tests in CI or other non-public, sandboxed environments.\n\nSome preparations and optimizations are not included. For example, given the near infinite permutations, images are not monitored for security vulnerabilities. Additionally, once images are published they are considered immutable and cannot be patched. That means (hypothetically) older images could become more vulnerable over time.\n\nThis means they should **not** be used for production deployment and security scans should be performed as-needed by users of these images.\n\n## Docker Hub\n\nAll of the images and tags are published to [Cypress on Docker Hub](https://hub.docker.com/u/cypress) under:\n\n- [https://hub.docker.com/r/cypress/factory](https://hub.docker.com/r/cypress/factory)\n- [https://hub.docker.com/r/cypress/base](https://hub.docker.com/r/cypress/base)\n- [https://hub.docker.com/r/cypress/browsers](https://hub.docker.com/r/cypress/browsers)\n- [https://hub.docker.com/r/cypress/included](https://hub.docker.com/r/cypress/included)\n\n## Cypress/Factory\n\nDon't see the exact combination of Cypress, Node.js and browser versions you need for your test environment? Checkout our [cypress/factory](factory). You can use it to generate a custom image to fit your needs.\n\n## Examples\n\n- Check out the documentation for each type of Cypress Docker image to read about example usage: [cypress/base](./base/README.md), [cypress/browsers](./browsers/README.md) and [cypress/included](./included/README.md) can all be used directly without change. Each of the Docker images can be used to build other images. [cypress/factory](./factory/README.md) is the preferred image to generate custom images.\n\n- Refer to [CI Docker examples](https://on.cypress.io/guides/continuous-integration/introduction#CI-Docker-examples) for links to examples of using Cypress Docker images with different Continuous Integration (CI) providers. See also the example workflow [.github/workflows/example-cypress-github-action.yml](./.github/workflows/example-cypress-github-action.yml) in this repository for CI usage with [cypress\u0026#8209;io/github\u0026#8209;action](https://github.com/cypress-io/github-action) running under the CI provider [GitHub Actions](https://docs.github.com/en/actions).\n\n## User\n\nBy default, Docker containers run as `root` user. [cypress/base](./base/README.md), [cypress/browsers](./browsers/README.md) and [cypress/included](./included/README.md) images provide the additional non-root user `node`.\n\nIf you run a Cypress Docker image locally as container with a non-root user, refer to the [Docker documentation](https://docs.docker.com/), such as [Docker Desktop FAQs](https://docs.docker.com/desktop/), for information on file-sharing between your host system and Docker. File-sharing details differ depending on the host operating system running Docker.\n\nIf you specify a Cypress Docker image in a [GitHub Actions job](https://docs.github.com/en/actions/using-jobs/running-jobs-in-a-container) `container` workflow section, add `options: --user 1001` to the workflow to avoid permissions issues.\n\n## Debug logs\n\nTo enable all Cypress debug logs when running Cypress in a Docker container, set the environment variable `DEBUG` to the value `cypress:*`. To filter the debug logs read [Log sources](https://on.cypress.io/troubleshooting#Log-sources) for alternate values of `DEBUG`.\n\n- For `docker run` in a command line, refer to [docker run: set environment variables](https://docs.docker.com/reference/cli/docker/container/run/#env) for options to pass environment variables to a Docker container.\n- In a Continuous Integration (CI) workflow using a Cypress Docker image, refer to your CI documentation for information on setting environment variables.\n\n## Known problems\n\n## Firefox not found\n\n### Problem\n\nWhen running in [GitHub Actions](https://docs.github.com/en/actions) using a `cypress/browsers` or `cypress/included` image and testing against the Mozilla Firefox browser with the default `root` user, Cypress may fail to detect an installed Firefox browser. Instead Cypress shows the following error message:\n\n\u003e Browser: firefox was not found on your system or is not supported by Cypress.\n\u003e Can't run because you've entered an invalid browser name.\n\nThe [GitHub Actions Runner](https://github.com/actions/runner) creates the `/github/home` directory with non-root ownership `1001` (`runner`) and sets the environment variable `HOME` to point to this directory. Firefox will not run with these settings. If the command `firefox --version` is executed, Firefox explains the restriction:\n\n\u003e Running Firefox as root in a regular user's session is not supported. ($HOME is /github/home which is owned by uid 1001.)\n\nSee [Cypress issue #27121](https://github.com/cypress-io/cypress/issues/27121).\n\n### Resolution\n\nTo allow Firefox to run in GitHub Actions in a Docker container, add `options: --user 1001` to the workflow to match GitHub Actions' `runner` user.\n\n```yml\ncontainer:\n  image: cypress/browsers\n  options: --user 1001\n```\n\nSee [Tags](#tags) section above for advice on selecting a non-default image tag.\n\n## EACCES permission denied binary_state.json\n\n### Problem\n\nIf a custom Docker image is built from a `cypress/base` or `cypress/browsers` Cypress Docker image, using a `Dockerfile` to install the Cypress binary (for instance with `npx cypress install`), and the custom image is then run as a container with a non-root user, Cypress will fail to run with an error message:\n\n\u003e Error: EACCES: permission denied, open '/root/.cache/Cypress/`\u003cCypress version\u003e`/binary_state.json'\n\nThis is due to an open Cypress issue [#30684](https://github.com/cypress-io/cypress/issues/30684) where Cypress fails to verify the installed Cypress binary if it does not have write access to the Cypress binary directory.\n\n### Workaround\n\nTo workaround this issue, either make the Cypress binary directory writable, or skip the Cypress binary verification.\n\nTo make the complete Cypress binary directory writable, add the following to the `Dockerfile` after the step to install the Cypress binary:\n\n```Dockerfile\nRUN chmod -R 777 /root/.cache/Cypress\n```\n\nTo skip Cypress binary verification using the environment variable `CYPRESS_SKIP_VERIFY`, described in the Cypress documentation [Advanced Installation](https://docs.cypress.io/app/references/advanced-installation#Environment-variables), either add the following to the `Dockerfile`:\n\n```Dockerfile\nENV CYPRESS_SKIP_VERIFY=true\n```\n\nor pass the environment variable as an additional CLI option `--env CYPRESS_SKIP_VERIFY=true` to the [docker run](https://docs.docker.com/reference/cli/docker/container/run/) command.\n\n## Fontconfig error: No writable cache directories\n\n### Problem\n\nIf a Cypress Docker image is run with a non-root user other than `node` (`1000`) then Cypress may be unable to write into the Linux `$HOME` directory and may fail. The error message contains the text:\n\n```text\nFontconfig error: No writable cache directories\nThe Test Runner unexpectedly exited via a exit event with signal SIGTRAP\n```\n\n### Workaround\n\nBuild a custom Docker image and add the following instructions to the end of the `Dockerfile` to allow the `$HOME` directory for the non-root user `node` to be used and to allow Cypress write access to the necessary cache directories:\n\n```Dockerfile\nENV HOME=/home/node\nRUN chmod -R 777 $HOME /root/.cache/Cypress\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## License\n\nSee [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypress-io%2Fcypress-docker-images","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcypress-io%2Fcypress-docker-images","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypress-io%2Fcypress-docker-images/lists"}