cypress-io · mjhenkes · Jan 17, 2023 · Dec 8, 2022 · Dec 14, 2022 · Dec 14, 2022
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -12,79 +12,47 @@ All contributors are expecting to abide by our [Code of Conduct](https://github.
 
 ⚠️ As a rule, unless there are extraordinary circumstances, we do NOT replace the existing Docker images. Replacing the images already used by people is dangerous, since it replaces the versions of tools without warning. We have such failed experience once, and do not want to repeat this mistake. Thus instead of replacing an existing image, in 99% of the cases we publish a new Docker image.
 
-### Add new base image
+### Building locally
 
-To create a new base image follow these steps
+We use docker compose to build the factory locally.
 
-1. run `yarn add:base -- <new version>` script. For example `yarn add:base -- 13.6.0`
-
-It will create a new folder `base/<new version>` and output versions of tools installed: Node, npm, yarn, etc. See [generate-base-image.js](scripts/generate-base-image.js) file for details.
-
-2. open a pull request.
-
-The new image will be built and tested on CI and pushed to Docker Hub once the PR is approved and merged to `master`.
-
-**note:** we install Chinese fonts in the base image to allow correct testing of [cypress-documentation](https://github.com/cypress-io/cypress-documentation) site that includes several translations of the Cypress docs. Without Chinese fonts the pages have broken rendering.
-
-### Add new browser image
-
-To create a new image with the specific browser versions needed to run your cypress tests.
-
-1. Run `yarn add:browser <base image tag> --chrome=<chrome version> --firefox=<firefox version> --edge`. For example `yarn add:browser 16.5.0 --chrome=94.0.4606.71 --firefox=93.0`.
-
-This will create a new folder `browser/node<node version>-chrome<chrome version>-ff<firefox version>-edge` See [generate-browser-image.js](scripts/generate-browser-image.js) file for details.
-
-2. Open a pull request.
-
-**Important ⚠️** In order to properly generate a browser image, you must specify a version of Chrome, or a version of Firefox, or a version of Edge.
-
-**note:** The Edge browser will always default to the latest stable release. There is currently no way to specify the downloaded version. For this reason, when generating an image with Edge support users should only pass `--edge`.
-
-**note:** No major browsers are currently compatible with `arm64`, so browsers images will be missing those browsers on `linux/arm64` architecture. As time passes and these become available, we will introduce them to the `arm64` images as well: https://github.com/cypress-io/cypress-docker-images/issues/695.
-
-### Add new included image
-
-To create a new image with Cypress pre-installed globally
-
-1. Run `yarn add:included -- <Cypress version> <base image tag>`. For example `yarn add:included -- 9.4.1 cypress/browsers:node16.13.2-chrome97-ff96`.
+```bash
+cd factory
+docker compose build factory
+```
 
-**Important ⚠️** please use `cypress/browsers` Docker image with the latest Node version matching the major version of Node included with Cypress. For example, if Cypress is shipping 16.5.0 and the latest 16.x is 16.14.0, ship the included image with Node 16.14.0.
+With the factory image built, you can now build the other included images
 
-This will create a new folder `included/<Cypress version>` See [generate-included-image.js](scripts/generate-included-image.js) file for details.
+```bash
+# This builds the 'included' image specified in the docker-compose file.
+docker compose build included
 
-2. Open a pull request.
+# This builds all images specified in the docker-compose file.
+docker compose build
+```
 
-#### Handling included images with different node versions
+Or you can then run tests in the test-project
 
-If there is already a `cypress/included` image with a specific version, but you need a different Node version or browser version, just create a new included image per the instructions above and a folder with the name `<Cypress version>-<base image tag> will be created.`
+```bash
+cd test-project
 
-**Important ⚠️** This only applies if there is an existing `cypress/included` image with the same version.
+# set the environment variables from factory/.env in your terminal.
+set -a && . ../.env && set +a
 
-## Tagging the latest image
+# run the test in an image built on top of the factory.
+docker compose run test-factory-all-included
+```
 
-We build individual base images that match Node versions: `10.18.1`, `12.12.0`, `12.18.2`, etc. We also tag some of the images with major version: `base:10`, `base:12`. We also tag one image `base:latest`. In general, you should use the explicit version like `base:12.18.0` because it guarantees that the Docker image will never be suddenly updated.
+### Updating images
 
-To tag new image, like `base:12.18.2` need to do the following from a local machine
+To produce new updated images, simply open a PR with the desired version(s) updated in the `factory/.env` file. Once the PR is merged into master the corresponding images will be pushed to dockerhub.
 
-```text
-# pull the image to tag
-$ docker pull cypress/base:12.18.2
-# tag that image with major version
-$ docker tag cypress/base:12.18.2 cypress/base:12
-# tag that image with "latest"
-$ docker tag cypress/base:12.18.2 cypress/base:latest
-
-# push the new images (which are the same)
-$ docker push cypress/base:12
-$ docker push cypress/base:latest
-```
+In general, `factory/.env` master should contain the latest versions we officially support. If you need to release an older version please modify `circle.yml` to push releases from a feature branch instead of setting the version in master to older versions.
 
 ## Minimize image sizes
 
 By default, the current base image is `bullseye-slim`. This dramatically decreases the size of all images. Other optimizations have been made to the Dockerfiles per Docker's recommendations.
 
-In order to allow for older images to be smaller, you can run the scripts above using existing node versions, Cypress versions, and browser versions. The scripts will recognize that a folder already exists, and append `-slim` to the folder. You can then update the folder name in your workflow, and use the images like you already were.
-
 Node versions less than or equal to Node 14 will use the `buster-slim` base image if they are recreated. Older images may still rely on `buster`.
 
 To see the final size of an image, you can use command [`docker images`](https://docs.docker.com/engine/reference/commandline/images/)
@@ -157,8 +125,6 @@ In CI, the images are built and tested in real `arm64` and `x64` architectures.
 └─────────────────────────────────────────────┘
 ```
 
-It would be nice to re-publish the Docker Hub images verbatim to ECR instead of building twice, but more work needs to be done in this area - see the `push-images` step in `circle.yml` for details.
-
 A current limitation is that no `arm64` images have browser binaries - see https://github.com/cypress-io/cypress-docker-images/issues/695 for details. [`global-profile.sh`](./scripts/for-images/global-profile.sh) is placed in `/etc/bash.bashrc`, so Arm Docker users will see a warning about this limitation.
 
 ### Updating images to add `linux/arm64`

diff --git a/README.md b/README.md
@@ -2,13 +2,14 @@
 
 These images provide all of the required dependencies for running Cypress in Docker.
 
-We build three main images, click on the image name to see the available tags and versions.
+We build four images, click on the image name to see the available tags and versions.
 
-| Image                        | Default                     | Description                                                                       | Monthly pulls                                                                                                                         |
-| ---------------------------- | --------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| [cypress/base](base)         | `cypress/base:16.13.0`      | 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/)         |
-| [cypress/browsers](browsers) | `cypress/browsers:chrome69` | All operating system dependencies and some browsers.                              | [![Docker Pulls](https://img.shields.io/docker/pulls/cypress/browsers.svg?maxAge=604800)](https://hub.docker.com/r/cypress/browsers/) |
-| [cypress/included](included) | `cypress/included:9.4.1`    | 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/) |
+| Image                                                          | Default                     | Description                                                                        | Monthly pulls                                                                                                                         |
+| -------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| [cypress/factory](https://hub.docker.com/r/cypress/factory/)   | `cypress/factory:1.0.0`    | 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/)   |
+| [cypress/base](https://hub.docker.com/r/cypress/base/)         | `cypress/base:16.13.0`      | 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/)         |
+| [cypress/browsers](https://hub.docker.com/r/cypress/browsers/) | `cypress/browsers:chrome69` | 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/) |
+| [cypress/included](https://hub.docker.com/r/cypress/included/) | `cypress/included:9.4.1`    | 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/) |
 
 Of these images, we provide multiple tags for various operating systems and specific browser versions. These allow you to target specific combinations you need.
 
@@ -20,10 +21,15 @@ It is recommended to use a specific image tag, and not rely on the `default` tag
 
 All of the images and tags are published to DockerHub under
 
+- [https://hub.docker.com/r/cypress/factory](https://hub.docker.com/r/cypress/factory)
 - [https://hub.docker.com/r/cypress/base](https://hub.docker.com/r/cypress/base)
 - [https://hub.docker.com/r/cypress/browsers](https://hub.docker.com/r/cypress/browsers)
 - [https://hub.docker.com/r/cypress/included](https://hub.docker.com/r/cypress/included)
 
+## Cypress/Factory
+
+Don't see the exact combination of cypress, node 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.
+
 ## Examples
 
 These images have all dependencies necessary to install and run Cypress. Just install your NPM dependencies (including Cypress) and run the tests. We utilize many of these docker images in our own projects, with different CI providers.