Add example zombienet network file and instructions (#1839)

* Add simple example on how to spin up network. * Update readme * Remove unnecessary prefix * Improve folder structure * Add link to file * Fix paths in readme * Update README.md Co-authored-by: Bastian Köcher <[email protected]> Co-authored-by: Bastian Köcher <[email protected]>
paritytech · Nov 8, 2022 · f68e124 · f68e124
1 parent 1e7948e
commit f68e124
Show file tree

Hide file tree

Showing 18 changed files with 104 additions and 58 deletions.
diff --git a/README.md b/README.md
@@ -37,10 +37,85 @@ 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`).
 
-## Installation
-
+## Installation and Setup
 Before building Cumulus SDK based nodes / runtimes prepare your environment by following Substrate [installation instructions](https://docs.substrate.io/main-docs/install/).
 
+To launch a local network, you can use [zombienet](https://github.com/paritytech/zombienet) for quick setup and experimentation or follow the [manual setup](#manual-setup).
+
+### Zombienet
+We use Zombienet to spin up networks for integration tests and local networks. Follow [these installation steps](https://github.com/paritytech/zombienet#requirements-by-provider) to set it up on your machine.
+A simple network specification with two relay chain nodes and one collator is located at [zombienet/examples/small_network.toml](zombienet/examples/small_network.toml).
+
+
+#### Which provider should I use?
+Zombienet offers multiple providers to run networks. Choose the one that best fits your needs:
+- **Podman:** Choose this if you want to spin up a network quick and easy.
+- **Native:** Choose this if you want to develop and deploy your changes. Requires compilation of the binaries.
+- **Kubernetes:** Choose this for advanced use-cases or running on cloud-infrastructure.
+
+#### How to run
+To run the example network, use the following commands:
+
+```bash
+# Podman provider
+zombienet --provider podman spawn ./zombienet/examples/small_network.toml
+
+# Native provider, assumes polkadot and polkadot-parachains binary in $PATH
+zombienet --provider native spawn ./zombienet/examples/small_network.toml
+```
+
+### Manual Setup
+#### Launch the Relay Chain
+
+```bash
+# Clone
+git clone https://github.com/paritytech/polkadot
+cd polkadot
+
+# Compile Polkadot with the real overseer feature
+cargo build --release --bin polkadot
+
+# Generate a raw chain spec
+./target/release/polkadot build-spec --chain rococo-local --disable-default-bootnode --raw > rococo-local-cfde.json
+
+# Alice
+./target/release/polkadot --chain rococo-local-cfde.json --alice --tmp
+
+# Bob (In a separate terminal)
+./target/release/polkadot --chain rococo-local-cfde.json --bob --tmp --port 30334
+```
+
+#### Launch the Parachain
+
+```bash
+# Clone
+git clone https://github.com/paritytech/cumulus
+cd cumulus
+
+# Compile
+cargo build --release --bin polkadot-parachain
+
+# Export genesis state
+./target/release/polkadot-parachain export-genesis-state > genesis-state
+
+# Export genesis wasm
+./target/release/polkadot-parachain export-genesis-wasm > genesis-wasm
+
+# Collator1
+./target/release/polkadot-parachain --collator --alice --force-authoring --tmp --port 40335 --ws-port 9946 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30335
+
+# Collator2
+./target/release/polkadot-parachain --collator --bob --force-authoring --tmp --port 40336 --ws-port 9947 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30336
+
+# Parachain Full Node 1
+./target/release/polkadot-parachain --tmp --port 40337 --ws-port 9948 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30337
+```
+
+#### Register the parachain
+
+![image](https://user-images.githubusercontent.com/2915325/99548884-1be13580-2987-11eb-9a8b-20be658d34f9.png)
+
+
 ## Statemint 🪙
 
 This repository also contains the Statemint runtime (as well as the canary runtime Statemine and the
@@ -63,7 +138,7 @@ CHAIN=westmint # or statemine
 ./target/release/polkadot-parachain --chain $CHAIN
 ```
 
-Refer to the [setup instructions below](#local-setup) to run a local network for development.
+Refer to the [setup instructions](#local-setup) to run a local network for development.
 
 ## Contracts 📝
 
@@ -117,60 +192,6 @@ The network uses horizontal message passing (HRMP) to enable communication betwe
 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.
 
-### Local Setup
-
-Launch a local setup including a Relay Chain and a Parachain.
-
-#### Launch the Relay Chain
-
-```bash
-# Clone
-git clone https://github.com/paritytech/polkadot
-cd polkadot
-
-# Compile Polkadot with the real overseer feature
-cargo build --release
-
-# Generate a raw chain spec
-./target/release/polkadot build-spec --chain rococo-local --disable-default-bootnode --raw > rococo-local-cfde.json
-
-# Alice
-./target/release/polkadot --chain rococo-local-cfde.json --alice --tmp
-
-# Bob (In a separate terminal)
-./target/release/polkadot --chain rococo-local-cfde.json --bob --tmp --port 30334
-```
-
-#### Launch the Parachain
-
-```bash
-# Clone
-git clone https://github.com/paritytech/cumulus
-cd cumulus
-
-# Compile
-cargo build --release
-
-# Export genesis state
-./target/release/polkadot-parachain export-genesis-state > genesis-state
-
-# Export genesis wasm
-./target/release/polkadot-parachain export-genesis-wasm > genesis-wasm
-
-# Collator1
-./target/release/polkadot-parachain --collator --alice --force-authoring --tmp --port 40335 --ws-port 9946 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30335
-
-# Collator2
-./target/release/polkadot-parachain --collator --bob --force-authoring --tmp --port 40336 --ws-port 9947 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30336
-
-# Parachain Full Node 1
-./target/release/polkadot-parachain --tmp --port 40337 --ws-port 9948 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30337
-```
-
-#### Register the parachain
-
-![image](https://user-images.githubusercontent.com/2915325/99548884-1be13580-2987-11eb-9a8b-20be658d34f9.png)
-
 ### Containerize
 
 After building `polkadot-parachain` with cargo or with Parity CI image as documented in [this chapter](#build--launch-rococo-collators),

diff --git a/scripts/ci/gitlab/pipeline/zombienet.yml b/scripts/ci/gitlab/pipeline/zombienet.yml
@@ -21,7 +21,7 @@
       artifacts:                   true
   variables:
     POLKADOT_IMAGE:                "docker.io/paritypr/polkadot-debug:master"
-    GH_DIR:                        "https://github.com/paritytech/cumulus/tree/${CI_COMMIT_SHORT_SHA}/zombienet_tests"
+    GH_DIR:                        "https://github.com/paritytech/cumulus/tree/${CI_COMMIT_SHORT_SHA}/zombienet/tests"
     COL_IMAGE:                     "docker.io/paritypr/test-parachain:${CI_COMMIT_REF_NAME}-${CI_COMMIT_SHORT_SHA}"
   allow_failure:                   true
   retry: 2

diff --git a/zombienet/examples/small_network.toml b/zombienet/examples/small_network.toml
@@ -0,0 +1,25 @@
+[relaychain]
+default_image = "parity/polkadot:latest"
+default_command = "polkadot"
+chain = "rococo-local"
+
+  [[relaychain.nodes]]
+  name = "alice"
+  validator = true
+
+  [[relaychain.nodes]]
+  name = "bob"
+  validator = true
+
+[[parachains]]
+id = 2000
+cumulus_based = true
+chain = "statemine-local"
+
+  # run charlie as parachain collator
+  [[parachains.collators]]
+  name = "charlie"
+  validator = true
+  image = "parity/polkadot-parachain:latest"
+  command = "polkadot-parachain"
+  args = ["--force-authoring"]
diff --git a/...om_tip_without_connected_collator.feature → ...om_tip_without_connected_collator.feature b/...om_tip_without_connected_collator.feature → ...om_tip_without_connected_collator.feature
diff --git a/..._from_tip_without_connected_collator.toml → ..._from_tip_without_connected_collator.toml b/..._from_tip_without_connected_collator.toml → ..._from_tip_without_connected_collator.toml
diff --git a/zombienet_tests/0002-pov_recovery.feature → zombienet/tests/0002-pov_recovery.feature b/zombienet_tests/0002-pov_recovery.feature → zombienet/tests/0002-pov_recovery.feature
diff --git a/zombienet_tests/0002-pov_recovery.toml → zombienet/tests/0002-pov_recovery.toml b/zombienet_tests/0002-pov_recovery.toml → zombienet/tests/0002-pov_recovery.toml
diff --git a/..._tests/0003-full_node_catching_up.feature → .../tests/0003-full_node_catching_up.feature b/..._tests/0003-full_node_catching_up.feature → .../tests/0003-full_node_catching_up.feature
diff --git a/...net_tests/0003-full_node_catching_up.toml → ...net/tests/0003-full_node_catching_up.toml b/...net_tests/0003-full_node_catching_up.toml → ...net/tests/0003-full_node_catching_up.toml
diff --git a/zombienet_tests/0004-runtime_upgrade.feature → zombienet/tests/0004-runtime_upgrade.feature b/zombienet_tests/0004-runtime_upgrade.feature → zombienet/tests/0004-runtime_upgrade.feature
diff --git a/zombienet_tests/0004-runtime_upgrade.toml → zombienet/tests/0004-runtime_upgrade.toml b/zombienet_tests/0004-runtime_upgrade.toml → zombienet/tests/0004-runtime_upgrade.toml
diff --git a/...t_tests/0005-migrate_solo_to_para.feature → ...t/tests/0005-migrate_solo_to_para.feature b/...t_tests/0005-migrate_solo_to_para.feature → ...t/tests/0005-migrate_solo_to_para.feature
diff --git a/...enet_tests/0005-migrate_solo_to_para.toml → ...enet/tests/0005-migrate_solo_to_para.toml b/...enet_tests/0005-migrate_solo_to_para.toml → ...enet/tests/0005-migrate_solo_to_para.toml
diff --git a/...s/0006-rpc_collator_builds_blocks.feature → ...s/0006-rpc_collator_builds_blocks.feature b/...s/0006-rpc_collator_builds_blocks.feature → ...s/0006-rpc_collator_builds_blocks.feature
diff --git a/...ests/0006-rpc_collator_builds_blocks.toml → ...ests/0006-rpc_collator_builds_blocks.toml b/...ests/0006-rpc_collator_builds_blocks.toml → ...ests/0006-rpc_collator_builds_blocks.toml
diff --git a/zombienet_tests/migrate_solo_to_para.js → zombienet/tests/migrate_solo_to_para.js b/zombienet_tests/migrate_solo_to_para.js → zombienet/tests/migrate_solo_to_para.js
diff --git a/zombienet_tests/register-para.js → zombienet/tests/register-para.js b/zombienet_tests/register-para.js → zombienet/tests/register-para.js
diff --git a/zombienet_tests/runtime_upgrade.js → zombienet/tests/runtime_upgrade.js b/zombienet_tests/runtime_upgrade.js → zombienet/tests/runtime_upgrade.js