Add information about the parity container image (#2783)

cumulus/README.md

@@ -5,6 +5,8 @@
 This repository contains both the Cumulus SDK and also specific chains implemented
 on top of this SDK.
 
+If you only want to run a **Polkadot Parachain Node**, check out our [container section](./docs/container.md).
+
 ## Cumulus SDK
 
 A set of tools for writing [Substrate](https://substrate.io/)-based
@@ -37,6 +39,8 @@ and treat as best.
 A Polkadot [collator](https://wiki.polkadot.network/docs/en/learn-collator) for the parachain is
 implemented by the `polkadot-parachain` binary (previously called `polkadot-collator`).
 
+You may run `polkadot-parachain` locally after building it or using one of the container option described [here](./docs/container.md).
+
 ### Relay Chain Interaction
 To operate a parachain node, a connection to the corresponding relay chain is necessary. This can be
 achieved in one of two ways:
@@ -220,19 +224,6 @@ To run a Rococo collator you will need to compile the following binary:
 cargo build --release --locked --bin polkadot-parachain
 ```
 
-Otherwise you can compile it with
-[Parity CI docker image](https://github.com/paritytech/scripts/tree/master/dockerfiles/ci-linux):
-
-```bash
-docker run --rm -it -w /shellhere/cumulus \
-                    -v $(pwd):/shellhere/cumulus \
-                    paritytech/ci-linux:production cargo build --release --locked --bin polkadot-parachain
-sudo chown -R $(id -u):$(id -g) target/
-```
-
-If you want to reproduce other steps of CI process you can use the following
-[guide](https://github.com/paritytech/scripts#gitlab-ci-for-building-docker-images).
-
 Once the executable is built, launch collators for each parachain (repeat once each for chain
 `tick`, `trick`, `track`):
 
@@ -240,6 +231,8 @@ Once the executable is built, launch collators for each parachain (repeat once e
 ./target/release/polkadot-parachain --chain $CHAIN --validator
 ```
 
+You can also build [using a container](./docs/container.md).
+
 ### Parachains
 
 * [Asset Hub](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frococo-statemint-rpc.polkadot.io#/explorer)
@@ -249,23 +242,3 @@ Once the executable is built, launch collators for each parachain (repeat once e
 The network uses horizontal message passing (HRMP) to enable communication between parachains and
 the relay chain and, in turn, between parachains. This means that every message is sent to the relay
 chain, and from the relay chain to its destination parachain.
-
-### Containerize
-
-After building `polkadot-parachain` with cargo or with Parity CI image as documented in [this chapter](#build--launch-rococo-collators),
-the following will allow producing a new docker image where the compiled binary is injected:
-
-```bash
-./docker/scripts/build-injected-image.sh
-```
-
-Alternatively, you can build an image with a builder pattern:
-
-```bash
-docker build --tag $OWNER/$IMAGE_NAME --file ./docker/polkadot-parachain_builder.Containerfile .
-
-You may then run your new container:
-
-```bash
-docker run --rm -it $OWNER/$IMAGE_NAME --collator --tmp --chain /specs/westmint.json
-```

cumulus/docs/container.md

@@ -0,0 +1,60 @@
+## Using Containers
+
+Using containers via **Podman** or **Docker** brings benefit, whether it is to build a container image or
+run a node while keeping a minimum footprint on your local system.
+
+This document mentions using `podman` or `docker`. Those are usually interchangeable and it is encouraged using preferably **Podman**. If you have podman installed and want to use all the commands mentioned below, you can simply create an alias with `alias docker=podman`.
+
+There are a few options to build a node within a container and inject a binary inside an image.
+
+### Parity built container image
+
+Parity builds and publishes a container image that can be found as `docker.io/parity/polkadot-parachain`.
+
+### Parity CI image
+
+Parity maintains and uses internally a generic "CI" image that can be used as a base to build binaries: [Parity CI container image](https://github.com/paritytech/scripts/tree/master/dockerfiles/ci-linux):
+
+The command below allows building a Linux binary without having to even install Rust or any dependency locally:
+
+```bash
+docker run --rm -it \
+	-w /shellhere/cumulus \
+    -v $(pwd):/shellhere/cumulus \
+    paritytech/ci-linux:production
+		cargo build --release --locked --bin polkadot-parachain
+sudo chown -R $(id -u):$(id -g) target/
+```
+
+If you want to reproduce other steps of CI process you can use the following
+[guide](https://github.com/paritytech/scripts#gitlab-ci-for-building-docker-images).
+
+### Injected image
+
+Injecting a binary inside a base image is the quickest option to get a working container image. This only works if you were able to build a Linux binary, either locally, or using a container as described above.
+
+After building a Linux binary ()`polkadot-parachain`) with cargo or with Parity CI image as documented above, the following command allows producing a new container image where the compiled binary is injected:
+
+```bash
+./docker/scripts/build-injected-image.sh
+```
+
+### Container build
+
+Alternatively, you can build an image with a builder pattern. This options takes a while but offers a simple method for anyone to get a working container image without requiring any of the Rust toolchain installed locally.
+
+```bash
+docker build \
+	--tag $OWNER/$IMAGE_NAME \
+	--file ./docker/polkadot-parachain_builder.Containerfile .
+```
+
+You may then run your new container:
+
+```bash
+docker run --rm -it \
+	$OWNER/$IMAGE_NAME \
+		--collator --tmp \
+		--execution wasm \
+		--chain /specs/westmint.json
+```