fix: update readme with more relevant/updated information (#630)

IMAGES.md

@@ -0,0 +1,81 @@
+# List of Docker images for `act`
+
+**Warning:** Below badges with size for each image are displaying size of **compressed image size in registry. After pulling the image, size can be drastically different due to Docker uncompressing the image layers.**
+
+## Images based on [`buildpack-deps`][hub/_/buildpack-deps]
+
+**Note 1: `node` images are based on Debian root filesystem, while it is extremely similar to Ubuntu, there might be some differences**
+
+**Note 2: `node` `-slim` images don't have `python` installed, if you want to use actions or software that is depending on `python`, you need to specify image manually**
+
+| Image                                     | Size                                                          |
+| ----------------------------------------- | ------------------------------------------------------------- |
+| [`node:12.20.1-buster`][hub/_/node]       | ![`buster-size`][hub/_/node/12.20.1-buster/size]              |
+| [`node:12.20.1-buster-slim`][hub/_/node]  | ![`micro-buster-size`][hub/_/node/12.20.1-buster-slim/size]   |
+| [`node:12.20.1-stretch`][hub/_/node]      | ![`stretch-size`][hub/_/node/12.20.1-stretch/size]            |
+| [`node:12.20.1-stretch-slim`][hub/_/node] | ![`micro-stretch-size`][hub/_/node/12.20.1-stretch-slim/size] |
+
+**Note: `catthehacker/ubuntu` images are based on Ubuntu root filesystem**
+
+| Image                                                       | Size                                                     | GitHub Repository                                             |
+| ----------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------- |
+| [`catthehacker/ubuntu:act-latest`][hub/catthehacker/ubuntu] | ![`act-latest`][hub/catthehacker/ubuntu/act-latest/size] | [`catthehacker/docker-images`][gh/catthehacker/docker_images] |
+| [`catthehacker/ubuntu:act-20.04`][hub/catthehacker/ubuntu]  | ![`act-20.04`][hub/catthehacker/ubuntu/act-20.04/size]   | [`catthehacker/docker-images`][gh/catthehacker/docker_images] |
+| [`catthehacker/ubuntu:act-18.04`][hub/catthehacker/ubuntu]  | ![`act-18.04`][hub/catthehacker/ubuntu/act-18.04/size]   | [`catthehacker/docker-images`][gh/catthehacker/docker_images] |
+| [`catthehacker/ubuntu:act-16.04`][hub/catthehacker/ubuntu]  | ![`act-16.04`][hub/catthehacker/ubuntu/act-16.04/size]   | [`catthehacker/docker-images`][gh/catthehacker/docker_images] |
+
+## Images based on [`actions/virtual-environments`][gh/actions/virtual-environments]
+
+**Note: `nektos/act-environments-ubuntu` have been last updated in February, 2020. It's recommended to update the image manually after `docker pull` if you decide to to use it.**
+
+| Image                                                                             | Size                                                                       | GitHub Repository                                       |
+| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------- |
+| [`nektos/act-environments-ubuntu:18.04`][hub/nektos/act-environments-ubuntu]      | ![`nektos:18.04`][hub/nektos/act-environments-ubuntu/18.04/size]           | [`nektos/act-environments`][gh/nektos/act-environments] |
+| [`nektos/act-environments-ubuntu:18.04-lite`][hub/nektos/act-environments-ubuntu] | ![`nektos:18.04-lite`][hub/nektos/act-environments-ubuntu/18.04-lite/size] | [`nektos/act-environments`][gh/nektos/act-environments] |
+| [`nektos/act-environments-ubuntu:18.04-full`][hub/nektos/act-environments-ubuntu] | ![`nektos:18.04-full`][hub/nektos/act-environments-ubuntu/18.04-full/size] | [`nektos/act-environments`][gh/nektos/act-environments] |
+
+| Image                                                       | Size                                                     | GitHub Repository                                             |
+| ----------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------- |
+| [`catthehacker/ubuntu:full-20.04`][hub/catthehacker/ubuntu] | ![`full-20.04`][hub/catthehacker/ubuntu/full-20.04/size] | [`catthehacker/docker-images`][gh/catthehacker/docker_images] |
+
+## Other images
+
+| Image                                                | Size                                              | GitHub Repository                                             |
+| ---------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------- |
+| [`catthehacker/alpine:act`][hub/catthehacker/alpine] | ![`alpine:act`][hub/catthehacker/alpine/act/size] | [`catthehacker/docker-images`][gh/catthehacker/docker_images] |
+
+Feel free to make a pull request with your image added here
+
+[hub/_/buildpack-deps]: https://hub.docker.com/_/buildpack-deps
+[hub/_/node]: https://hub.docker.com/r/_/node
+[hub/_/node/12.20.1-buster/size]: https://img.shields.io/docker/image-size/_/node/12.20.1-buster
+[hub/_/node/12.20.1-buster-slim/size]: https://img.shields.io/docker/image-size/_/node/12.20.1-buster-slim
+[hub/_/node/12.20.1-stretch/size]: https://img.shields.io/docker/image-size/_/node/12.20.1-stretch
+[hub/_/node/12.20.1-stretch-slim/size]: https://img.shields.io/docker/image-size/_/node/12.20.1-stretch-slim
+[hub/catthehacker/ubuntu]: https://hub.docker.com/r/catthehacker/ubuntu
+[hub/catthehacker/ubuntu/act-latest/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/act-latest
+[hub/catthehacker/ubuntu/act-20.04/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/act-20.04
+[hub/catthehacker/ubuntu/act-18.04/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/act-18.04
+[hub/catthehacker/ubuntu/act-16.04/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/act-16.04
+[hub/catthehacker/ubuntu/full-20.04/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/full-20.04
+[hub/nektos/act-environments-ubuntu]: https://hub.docker.com/r/nektos/act-environments-ubuntu
+[hub/nektos/act-environments-ubuntu/18.04/size]: https://img.shields.io/docker/image-size/nektos/act-environments-ubuntu/18.04
+[hub/nektos/act-environments-ubuntu/18.04-lite/size]: https://img.shields.io/docker/image-size/nektos/act-environments-ubuntu/18.04-lite
+[hub/nektos/act-environments-ubuntu/18.04-full/size]: https://img.shields.io/docker/image-size/nektos/act-environments-ubuntu/18.04-full
+
+<!-- Other images links -->
+
+[hub/catthehacker/alpine]: https://hub.docker.com/r/catthehacker/alpine
+[hub/catthehacker/alpine/act/size]: https://img.shields.io/docker/image-size/catthehacker/alpine/act
+
+<!--
+[hub/<username>/<image>]: https://hub.docker.com/r/[username]/[image]
+[hub/<username>/<image>/<tag>/size]: https://img.shields.io/docker/image-size/[username]/[image]/[tag]
+-->
+
+<!-- GitHub repository links -->
+
+[gh/nektos/act-environments]: https://github.com/nektos/act-environments
+[gh/actions/virtual-environments]: https://github.com/actions/virtual-environments
+[gh/catthehacker/docker_images]: https://github.com/catthehacker/docker_images
+[gh/catthehacker/virtual-environments]: https://github.com/catthehacker/virtual-environments

README.md

@@ -1,6 +1,6 @@
 ![](https://github.com/nektos/act/wiki/img/logo-150.png)
 
-# Overview [![push](https://github.com/nektos/act/workflows/push/badge.svg?branch=master&event=push)](https://github.com/nektos/act/actions) [![Join the chat at https://gitter.im/nektos/act](https://badges.gitter.im/nektos/act.svg)](https://gitter.im/nektos/act?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Go Report Card](https://goreportcard.com/badge/github.com/nektos/act)](https://goreportcard.com/report/github.com/nektos/act)[![awesome-runners](https://img.shields.io/badge/listed%20on-awesome--runners-blue.svg)](https://github.com/jonico/awesome-runners)
+# Overview [![push](https://github.com/nektos/act/workflows/push/badge.svg?branch=master&event=push)](https://github.com/nektos/act/actions) [![Join the chat at https://gitter.im/nektos/act](https://badges.gitter.im/nektos/act.svg)](https://gitter.im/nektos/act?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Go Report Card](https://goreportcard.com/badge/github.com/nektos/act)](https://goreportcard.com/report/github.com/nektos/act) [![awesome-runners](https://img.shields.io/badge/listed%20on-awesome--runners-blue.svg)](https://github.com/jonico/awesome-runners)
 
 
 > "Think globally, `act` locally"
@@ -20,34 +20,66 @@ Let's see it in action with a [sample repo](https://github.com/cplee/github-acti
 
 # Installation
 
+## Necessary prerequisites for running `act`
+`act` depends on `docker` to run workflows.
+
+If you are using macOS, please be sure to follow the steps outlined in [Docker Docs for how to install Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/).
+
+If you are using Windows, please follow steps for [installing Docker Desktop on Windows](https://docs.docker.com/docker-for-windows/install/).
+
+If you are using Linux, you will need to [install Docker Engine](https://docs.docker.com/engine/install/).
+
+`act` is currently not supported with `podman` or other container backends (it might work, but it's not guaranteed). Please see [#303](https://github.com/nektos/act/issues/303) for updates.
+
+## Homebrew
+
 To install with [Homebrew](https://brew.sh/), run:
 
-`brew install act`
+```shell
+brew install act
+```
 
 Alternatively, you can use the following:
 
-`curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash`
+```shell
-
+curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
-NOTE: Currently not compatible with Apple Silicon (ARM). This project relies on Docker which has not been ported to Apple Silicon yet.
+```
 
 If you are running Windows, download the [latest release](https://github.com/nektos/act/releases/latest) and add the binary into your PATH.
 If you are using [Chocolatey](https://chocolatey.org/) then run:
-`choco install act-cli`
+
+[![](https://img.shields.io/chocolatey/v/act-cli)](https://community.chocolatey.org/packages/act-cli)
+```shell
+choco install act-cli
+```
 
 If you are using [Scoop](https://scoop.sh/) then run:
-`scoop install act`
+
+[![](https://img.shields.io/scoop/v/act)](https://github.com/ScoopInstaller/Main/blob/master/bucket/act.json)
+
+```shell
+scoop install act
+```
 
 If you are running Arch Linux, you can install the [act](https://aur.archlinux.org/packages/act/) package with your favorite package manager:
 
-`yay -S act`
+[![](https://img.shields.io/aur/version/act)](https://aur.archlinux.org/packages/act/)
+
+```shell
+yay -S act
+```
 
 If you are using NixOS or the Nix package manager on another platform you can install act globally by running
 
-`nix-env -iA nixpkgs.act`
+```sh
+nix-env -iA nixpkgs.act
+```
 
 or in a shell by running
 
-`nix-shell -p act`
+```sh
+nix-shell -p act
+```
 
 # Commands
 
@@ -117,6 +149,8 @@ It will save that information to `~/.actrc`, please refer to [Configuration](#co
 
 # Known Issues
 
+## `MODULE_NOT_FOUND`
+
 A `MODULE_NOT_FOUND` during `docker cp` command [#228](https://github.com/nektos/act/issues/228) can happen if you are relying on local changes that have not been pushed. This can get triggered if the action is using a path, like:
 
 ```yaml
@@ -137,42 +171,53 @@ steps:
 
 If the `path:` value doesn't match the name of the repository, a `MODULE_NOT_FOUND` will be thrown.
 
+## `act` on Windows
+
+Running `act` on Windows host is currently broken - see [#587](https://github.com/nektos/act/issues/587)
+
 # Runners
 
 GitHub Actions offers managed [virtual environments](https://help.github.com/en/actions/reference/virtual-environments-for-github-hosted-runners) for running workflows. In order for `act` to run your workflows locally, it must run a container for the runner defined in your workflow file. Here are the images that `act` uses for each runner type and size:
 
 | GitHub Runner   | Micro Docker Image                   | Medium Docker Image                        | Large Docker Image                                     |
-| ------------- | ---------------------------------- | ---------------------------------------- | --------------------------------------------- |
+| --------------- | ------------------------------------ | ------------------------------------------ | ------------------------------------------------------ |
-| ubuntu-latest | [node:12.20.1-buster-slim][micro]  | [catthehacker/ubuntu:act-latest][medium] | `unavailable`                                 |
+| `ubuntu-latest` | [`node:12.20.1-buster-slim`][micro]  | [`catthehacker/ubuntu:act-latest`][medium] | [`catthehacker/ubuntu:full-20.04`][large-cat]          |
-| ubuntu-20.04  | [node:12.20.1-buster-slim][micro]  | [catthehacker/ubuntu:act-20.04][medium]  | `unavailable`                                 |
+| `ubuntu-20.04`  | [`node:12.20.1-buster-slim`][micro]  | [`catthehacker/ubuntu:act-20.04`][medium]  | [`catthehacker/ubuntu:full-20.04`][large-cat]          |
-| ubuntu-18.04  | [node:12.20.1-buster-slim][micro]  | [catthehacker/ubuntu:act-18.04][medium]  | [nektos/act-environments-ubuntu:18.04][large] |
+| `ubuntu-18.04`  | [`node:12.20.1-buster-slim`][micro]  | [`catthehacker/ubuntu:act-18.04`][medium]  | [`nektos/act-environments-ubuntu:18.04`][large-act]    |
-| ubuntu-16.04  | [node:12.20.1-stretch-slim][micro] | [catthehacker/ubuntu:act-16.04][medium]  | `unavailable`                                 |
+| `ubuntu-16.04`  | [`node:12.20.1-stretch-slim`][micro] | [`catthehacker/ubuntu:act-16.04`][medium]  | `unavailable`                                          |
 
-Below platforms are currently **unsupported and won't work** (see issue [#97])
+[micro]: https://hub.docker.com/_/buildpack-deps
+[medium]: https://github.com/catthehacker/docker_images
+[large-cat]: https://github.com/catthehacker/act-environments
+[large-act]: https://github.com/nektos/act-environments
+
+Below platforms are currently **unsupported and won't work** (see issue [#97](https://github.com/nektos/act/issues/97))
 
 - `windows-latest`
 - `windows-2019`
 - `macos-latest`
 - `macos-10.15`
 
-[micro]: https://hub.docker.com/_/buildpack-deps
+## Please see [IMAGES.md](./IMAGES.md) for more information about the Docker images that can be used with `act`
-[medium]: https://github.com/catthehacker/docker_images
-[large]: https://github.com/nektos/act-environments
-[#97]: https://github.com/nektos/act/issues/97
 
 ## Default runners are intentionally incomplete
 
 These default images do **not** contain **all** the tools that GitHub Actions offers by default in their runners.
 Many things can work improperly or not at all while running those image.
+Additionally, some software might still not work even if installed properly, since GitHub Actions are running in fully virtualized machines while `act` is using Docker containers (e.g. Docker does not support running `systemd`).
+In case of any problems [please create issue](https://github.com/nektos/act/issues/new/choose) in respective repository (issues with `act` in this repository, issues with `nektos/act-environments-ubuntu:18.04` in [`nektos/act-environments`](https://github.com/nektos/act-environments) and issues with any image from user `catthehacker` in [`catthehacker/docker_images`](https://github.com/catthehacker/docker_images))
 
 ## Alternative runner images
 
 If you need an environment that works just like the corresponding GitHub runner then consider using an image provided by [nektos/act-environments](https://github.com/nektos/act-environments):
 
-- [nektos/act-environments-ubuntu:18.04](https://hub.docker.com/r/nektos/act-environments-ubuntu/tags) - built from the Packer file GitHub uses in [actions/virtual-environments](https://github.com/actions/runner).
+- [`nektos/act-environments-ubuntu:18.04`](https://hub.docker.com/r/nektos/act-environments-ubuntu/tags) - built from the Packer file GitHub uses in [actions/virtual-environments](https://github.com/actions/runner).
 
 :warning: :elephant: `*** WARNING - this image is >18GB 😱***`
 
+- [`catthehacker/ubuntu:full-20.04`](https://hub.docker.com/r/catthehacker/ubuntu/tags) - built from Dockerfile based on the Packer template from [actions/virtual-environments](https://github.com/actions/runner).
+This image size is about `61GB` unpacked (`23GB` compressed) but contains more recent software versions (as of date of build).
+
 ## Use an alternative runner image
 
 To use a different image for the runner, use the `-P` option.
@@ -272,6 +317,5 @@ Want to contribute to act? Awesome! Check out the [contributing guidelines](CONT
 
 - Install Go tools 1.16+ - (https://golang.org/doc/install)
 - Clone this repo `git clone git@github.com:nektos/act.git`
-- Pull the default docker image `docker pull nektos/act-environments-ubuntu:18.04`
 - Run unit tests with `make test`
 - Build and install: `make install`