├── .github ├── CODEOWNERS ├── ISSUE_TEMPLATE │ ├── 1_user_support.yml │ ├── 2_bug_report.txt │ ├── 3_proposal.yml │ └── config.yml └── workflows │ └── docs.yml ├── .gitignore ├── .markdownlint.json ├── README.md ├── book.toml ├── last-changed.css └── src ├── README.md ├── SUMMARY.md ├── _site ├── main.js ├── style.css └── version.js ├── deployments ├── example.md ├── index.md ├── options.md ├── parachain-node-diagram.drawio.svg ├── roles.md └── targets.md ├── explanations ├── chainspecs.md ├── index.md └── keys_accounts.md ├── guides ├── collator_deployment.md ├── index.md ├── parachain_deployment.md ├── readiness-checklist.md ├── rpc_index.md ├── rpc_kubernetes.md └── subkey.md ├── icons ├── feeds.png ├── figma.png ├── github.png ├── gitlab.png ├── jira.png └── webhooks.png ├── images ├── 3osxC7.png ├── AEEVr6.png ├── lb0gOx.png ├── metric_dashboard.png ├── rococo-collators-1002.png ├── rococo-parachains.png ├── rococo-validator-a-node-0.png ├── testnet-mgr-api.png └── testnet-mgr.png ├── kubernetes ├── helm.md ├── index.md ├── key_injection_test.md └── testnetmanager.md ├── monitoring ├── index.md ├── infrastructure.md └── polkadot_sdk.md ├── overview.md ├── references └── index.md └── serverdeploy ├── automation.md ├── index.md ├── logging.md └── systemd.md /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners 2 | 3 | * @peaceiris 4 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/1_user_support.yml: -------------------------------------------------------------------------------- 1 | name: User Support 2 | description: Questions for this action 3 | title: "support: " 4 | labels: support 5 | assignees: peaceiris 6 | body: 7 | - type: markdown 8 | attributes: 9 | value: Please note we will close your issue without comment if you do not fill out the issue checklist below and provide ALL the requested information. 10 | - type: checkboxes 11 | attributes: 12 | label: Checklist. 13 | description: Checklist before creating an issue. 14 | options: 15 | - label: I am using the latest version of this action. 16 | required: true 17 | - label: I have read the latest README and followed the instructions. 18 | required: true 19 | - label: I have read the latest GitHub Actions official documentation and learned the basic spec and concepts. 20 | required: true 21 | - type: textarea 22 | attributes: 23 | label: Describe your question 24 | description: A clear and concise description of what the question is. 25 | validations: 26 | required: true 27 | - type: textarea 28 | attributes: 29 | label: Relevant links 30 | description: 31 | Links to your public repository, YAML config file, and YAML workflow file. 32 | Please use [a permanent link](https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/getting-permanent-links-to-files), not a default branch. 33 | render: markdown 34 | value: | 35 | Public repository: 36 | YAML config: 37 | YAML workflow: 38 | validations: 39 | required: true 40 | - type: textarea 41 | attributes: 42 | label: Relevant log output 43 | description: Copy and paste any relevant log output here. 44 | validations: 45 | required: false 46 | - type: textarea 47 | attributes: 48 | label: Additional context. 49 | description: Write any other context about the question here. 50 | validations: 51 | required: false 52 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/2_bug_report.txt: -------------------------------------------------------------------------------- 1 | name: Bug Report 2 | description: Try the User Support Issue Template first. 3 | title: 'bug: ' 4 | labels: bug 5 | assignees: peaceiris 6 | body: 7 | - type: markdown 8 | attributes: 9 | value: 10 | Please note we will close your issue without comment if you do not fill out the issue checklist below and provide ALL the requested information. 11 | - type: checkboxes 12 | attributes: 13 | label: Checklist 14 | description: Checklist before creating an issue. 15 | options: 16 | - label: "I am using the latest version of this action." 17 | required: true 18 | - label: "I have read the latest README and followed the instructions." 19 | required: true 20 | - label: "I have read the latest GitHub Actions official documentation and learned the basic spec and concepts." 21 | required: true 22 | - type: textarea 23 | attributes: 24 | label: "Describe the bug" 25 | description: "A clear and concise description of what the bug is." 26 | validations: 27 | required: true 28 | - type: textarea 29 | attributes: 30 | label: Relevant links 31 | description: 32 | Links to your public repository, YAML config file, and YAML workflow file. 33 | Please use [a permanent link](https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/getting-permanent-links-to-files), not a default branch. 34 | render: markdown 35 | value: | 36 | Public repository: 37 | YAML config: 38 | YAML workflow: 39 | validations: 40 | required: true 41 | - type: textarea 42 | attributes: 43 | label: Relevant log output 44 | description: Copy and paste any relevant log output here. 45 | validations: 46 | required: false 47 | - type: textarea 48 | attributes: 49 | label: Additional context. 50 | description: Write any other context about the question here. 51 | validations: 52 | required: false 53 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/3_proposal.yml: -------------------------------------------------------------------------------- 1 | name: Proposal 2 | description: Suggest an idea for this project 3 | title: "proposal: " 4 | labels: proposal 5 | assignees: peaceiris 6 | body: 7 | - type: markdown 8 | attributes: 9 | value: Please note we will close your issue without comment if you do not fill out the issue checklist below and provide ALL the requested information. 10 | - type: checkboxes 11 | attributes: 12 | label: Checklist 13 | description: Checklist before creating an issue. 14 | options: 15 | - label: I am using the latest version of this action. 16 | required: true 17 | - label: I have read the latest README and followed the instructions. 18 | required: true 19 | - label: I have read the latest GitHub Actions official documentation and learned the basic spec and concepts. 20 | required: true 21 | - type: textarea 22 | attributes: 23 | label: Describe your proposal. 24 | description: A clear and concise description of what the proposal is. 25 | validations: 26 | required: true 27 | - type: textarea 28 | attributes: 29 | label: Describe the solution you'd like. 30 | description: A clear and concise description of what you want to happen. 31 | validations: 32 | required: true 33 | - type: textarea 34 | attributes: 35 | label: Describe alternatives you've considered. 36 | description: A clear and concise description of any alternative solutions or features you've considered. 37 | validations: 38 | required: false 39 | - type: textarea 40 | attributes: 41 | label: Additional context. 42 | description: Add any other context or screenshots about the feature request here. 43 | validations: 44 | required: false 45 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | contact_links: 3 | - name: Discussions 4 | url: https://github.com/peaceiris/actions-gh-pages/discussions 5 | about: Ask casual questions or share your story about the GitHub Pages Action. 6 | - name: GitHub Actions - GitHub Support Community Forum 7 | url: https://github.community/c/code-to-cloud/github-actions/41 8 | about: Please ask questions about GitHub Actions here. 9 | - name: GitHub Pages Documentation 10 | url: https://docs.github.com/en/pages 11 | about: GitHub Pages official documentaion here. 12 | - name: GitHub Actions Documentation 13 | url: https://docs.github.com/en/actions 14 | about: GitHub Actions official documentation here. 15 | -------------------------------------------------------------------------------- /.github/workflows/docs.yml: -------------------------------------------------------------------------------- 1 | name: github pages 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | pull_request: 8 | 9 | jobs: 10 | deploy: 11 | runs-on: ubuntu-20.04 12 | concurrency: 13 | group: ${{ github.workflow }}-${{ github.ref }} 14 | steps: 15 | - uses: actions/checkout@v2 16 | 17 | - name: Setup mdBook 18 | uses: peaceiris/actions-mdbook@v1 19 | with: 20 | mdbook-version: 0.4.10 21 | 22 | - run: cargo install mdbook-last-changed 23 | - run: mdbook build 24 | 25 | - name: Deploy 26 | uses: peaceiris/actions-gh-pages@v3 27 | if: ${{ github.ref == 'refs/heads/main' }} 28 | with: 29 | github_token: ${{ secrets.GITHUB_TOKEN }} 30 | keep_files: true 31 | publish_dir: ./book 32 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | book/* 2 | .idea/ -------------------------------------------------------------------------------- /.markdownlint.json: -------------------------------------------------------------------------------- 1 | { 2 | "MD013": false, 3 | "MD033": false 4 | } 5 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Parachain DevOps Guidebook 2 | 3 | [https://paritytech.github.io/devops-guide/](https://paritytech.github.io/devops-guide/) 4 | -------------------------------------------------------------------------------- /book.toml: -------------------------------------------------------------------------------- 1 | [book] 2 | authors = ["Parity DevOps Team", "ddorgan", "PierreBesson"] 3 | language = "en" 4 | multilingual = false 5 | src = "src" 6 | title = "Parachain Devops Guide" 7 | 8 | [output.html] 9 | additional-css = ["last-changed.css"] 10 | default-theme = "Light" 11 | git-repository-url = "https://github.com/paritytech/devops-guide" 12 | git-repository-icon = "fa-github" 13 | edit-url-template = "https://github.com/paritytech/devops-guide/edit/master/{path}" 14 | site-url = "/devops-guide/" 15 | 16 | [preprocessor.last-changed] 17 | command = "mdbook-last-changed" 18 | renderer = ["html"] 19 | -------------------------------------------------------------------------------- /last-changed.css: -------------------------------------------------------------------------------- 1 | footer { 2 | font-size: 0.8em; 3 | text-align: center; 4 | border-top: 1px solid black; 5 | padding: 5px 0; 6 | } 7 | -------------------------------------------------------------------------------- /src/README.md: -------------------------------------------------------------------------------- 1 |

2 | GitHub Actions for mdBook 3 |

4 | 5 |
6 | GitHub Actions for mdBook thumbnail 7 |
8 | 9 | [![license](https://img.shields.io/github/license/peaceiris/actions-mdbook.svg)](https://github.com/peaceiris/actions-mdbook/blob/main/LICENSE) 10 | [![release](https://img.shields.io/github/release/peaceiris/actions-mdbook.svg)](https://github.com/peaceiris/actions-mdbook/releases/latest) 11 | [![GitHub release date](https://img.shields.io/github/release-date/peaceiris/actions-mdbook.svg)](https://github.com/peaceiris/actions-mdbook/releases) 12 | ![Test](https://github.com/peaceiris/actions-mdbook/workflows/Test/badge.svg?branch=main&event=push) 13 | [![CodeFactor](https://www.codefactor.io/repository/github/peaceiris/actions-mdbook/badge)](https://www.codefactor.io/repository/github/peaceiris/actions-mdbook) 14 | [![codecov](https://codecov.io/gh/peaceiris/actions-mdbook/branch/main/graph/badge.svg)](https://codecov.io/gh/peaceiris/actions-mdbook) 15 | [![Release Feed](https://img.shields.io/badge/release-feed-yellow)](https://github.com/peaceiris/actions-mdbook/releases.atom) 16 | 17 | [rust-lang/mdBook] Setup Action. 18 | 19 | [rust-lang/mdBook]: https://github.com/rust-lang/mdBook 20 | 21 | We can run **mdBook** on a virtual machine of **GitHub Actions** by this mdBook action. 22 | Linux, macOS, and Windows are supported. 23 | 24 | | OS (runs-on) | ubuntu-18.04, ubuntu-20.04 | macos-latest | windows-2019 | 25 | |---|:---:|:---:|:---:| 26 | | Support | ✅️ | ✅️ | ✅️ | 27 | 28 | 29 | 30 | ## Table of Contents 31 | 32 | 33 | 34 | 35 | 36 | - [Getting Started](#getting-started) 37 | - [⭐️ Create your workflow](#%EF%B8%8F-create-your-workflow) 38 | - [Options](#options) 39 | - [⭐️ Use the latest version of mdBook](#%EF%B8%8F-use-the-latest-version-of-mdbook) 40 | - [Tips](#tips) 41 | - [⭐️ Read mdBook version from file](#%EF%B8%8F-read-mdbook-version-from-file) 42 | - [CHANGELOG](#changelog) 43 | - [License](#license) 44 | - [About Maintainer](#about-maintainer) 45 | - [Maintainer Notes](#maintainer-notes) 46 | 47 | 48 | 49 | 50 | 51 | ## Getting Started 52 | 53 | ### ⭐️ Create your workflow 54 | 55 | An example workflow `.github/workflows/gh-pages.yml` with [GitHub Actions for GitHub Pages]. 56 | For the first deployment, we have to do this operation: [First Deployment with `GITHUB_TOKEN` - peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-first-deployment-with-github_token) 57 | 58 | [GitHub Actions for GitHub Pages]: https://github.com/peaceiris/actions-gh-pages 59 | 60 | [![peaceiris/actions-gh-pages - GitHub](https://gh-card.dev/repos/peaceiris/actions-gh-pages.svg?fullname)](https://github.com/peaceiris/actions-gh-pages) 61 | 62 | ```yaml 63 | name: github pages 64 | 65 | on: 66 | push: 67 | branches: 68 | - main 69 | pull_request: 70 | 71 | jobs: 72 | deploy: 73 | runs-on: ubuntu-20.04 74 | concurrency: 75 | group: ${{ github.workflow }}-${{ github.ref }} 76 | steps: 77 | - uses: actions/checkout@v2 78 | 79 | - name: Setup mdBook 80 | uses: peaceiris/actions-mdbook@v1 81 | with: 82 | mdbook-version: '0.4.10' 83 | # mdbook-version: 'latest' 84 | 85 | - run: mdbook build 86 | 87 | - name: Deploy 88 | uses: peaceiris/actions-gh-pages@v3 89 | if: ${{ github.ref == 'refs/heads/main' }} 90 | with: 91 | github_token: ${{ secrets.GITHUB_TOKEN }} 92 | publish_dir: ./book 93 | ``` 94 | 95 |
96 | Back to TOC ☝️ 97 |
98 | 99 | 100 | 101 | ## Options 102 | 103 | ### ⭐️ Use the latest version of mdBook 104 | 105 | Set `mdbook-version: 'latest'` to use the latest version of mdBook. 106 | 107 | ```yaml 108 | - name: Setup mdBook 109 | uses: peaceiris/actions-mdbook@v1 110 | with: 111 | mdbook-version: 'latest' 112 | ``` 113 | 114 | This action fetches the latest version of mdBook by [mdbook — Homebrew Formulae](https://formulae.brew.sh/formula/mdbook) 115 | 116 |
117 | Back to TOC ☝️ 118 |
119 | 120 | 121 | 122 | ## Tips 123 | 124 | ### ⭐️ Read mdBook version from file 125 | 126 | How to sync a mdBook version between a Docker Compose and a GitHub Actions workflow via `.env` file. 127 | 128 | Write a `MDBOOK_VERSION` to the `.env` file like the following and push it to a remote branch. 129 | 130 | ```sh 131 | MDBOOK_VERSION=0.4.10 132 | ``` 133 | 134 | Next, add a step to read a mdBook version from the `.env` file. 135 | 136 | ```yaml 137 | - name: Read .env 138 | id: mdbook-version 139 | run: | 140 | . ./.env 141 | echo "MDBOOK_VERSION=${MDBOOK_VERSION}" >> $GITHUB_OUTPUT 142 | 143 | - name: Setup mdBook 144 | uses: peaceiris/actions-mdbook@v1 145 | with: 146 | mdbook-version: '${{ steps.mdbook-version.outputs.MDBOOK_VERSION }}' 147 | ``` 148 | 149 | Here is a `docker-compose.yml` example. 150 | 151 | ```yaml 152 | version: '3' 153 | 154 | services: 155 | mdbook: 156 | container_name: mdbook 157 | image: "peaceiris/mdbook:v${MDBOOK_VERSION}" 158 | # image: "peaceiris/mdbook:v${MDBOOK_VERSION}-rust" # Large image including Rust compiler 159 | stdin_open: true 160 | tty: true 161 | ports: 162 | - 3000:3000 163 | - 3001:3001 164 | volumes: 165 | - ${PWD}:/book 166 | command: 167 | - serve 168 | - --hostname 169 | - '0.0.0.0' 170 | ``` 171 | 172 | The alpine base mdBook Docker image is provided on the following repository. 173 | 174 | > [peaceiris/docker-mdbook: mdBook Alpine Base Docker Image.](https://github.com/peaceiris/docker-mdbook) 175 | 176 |
177 | Back to TOC ☝️ 178 |
179 | 180 | 181 | 182 | ## CHANGELOG 183 | 184 | - [CHANGELOG.md](CHANGELOG.md) 185 | 186 | 187 | 188 | ## License 189 | 190 | - [MIT License - peaceiris/actions-mdbook] 191 | 192 | [MIT License - peaceiris/actions-mdbook]: https://github.com/peaceiris/actions-mdbook/blob/main/LICENSE 193 | 194 | 195 | 196 | ## About Maintainer 197 | 198 | - [peaceiris homepage](https://peaceiris.com/) 199 | - [GitHub Action Hero: Shohei Ueda - The GitHub Blog](https://github.blog/2020-03-22-github-action-hero-shohei-ueda/) 200 | 201 | 202 | 203 | ## Maintainer Notes 204 | 205 | Run `npm` and `git commit` commands on a container. 206 | 207 | **On Host** 208 | 209 | ```sh 210 | # Docker 211 | make build 212 | make run 213 | make run cmd="env" 214 | make test 215 | make commit msg="chore: Add Makefile" 216 | 217 | # Release 218 | ./release.sh 219 | ``` 220 | 221 | 222 | 223 |
224 | Back to TOC ☝️ 225 |
226 | -------------------------------------------------------------------------------- /src/SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | - [Overview](./overview.md) 4 | - [subkey](./guides/subkey.md) 5 | - [How-to Guides](./guides/index.md) 6 | - [Parachain Deployment](./guides/parachain_deployment.md) 7 | - [RPC Deployment](./guides/rpc_index.md) 8 | - [Kubernetes](./guides/rpc_kubernetes.md) 9 | - [Collator Deployment](./guides/collator_deployment.md) 10 | - [Parachain Readiness Checklist](./guides/readiness-checklist.md) 11 | - [Explanations](./explanations/index.md) 12 | - [Deployment Options](./deployments/index.md) 13 | - [Node Roles](./deployments/roles.md) 14 | - [Remote Targets](./deployments/targets.md) 15 | - [Role Specific Arguments](./deployments/options.md) 16 | - [Server Deployments](./serverdeploy/index.md) 17 | - [Systemd](./serverdeploy/systemd.md) 18 | - [Logging](./serverdeploy/logging.md) 19 | - [Automation](./serverdeploy/automation.md) 20 | - [Kubernetes Deployments](./kubernetes/index.md) 21 | - [Helm Chart](./kubernetes/helm.md) 22 | - [Key Injection Example](./kubernetes/key_injection_test.md) 23 | - [Testnet Manager](./kubernetes/testnetmanager.md) 24 | - [Monitoring](./monitoring/index.md) 25 | - [Intrastructure](./monitoring/infrastructure.md) 26 | - [Polkadot SDK](./monitoring/polkadot_sdk.md) 27 | - [Keys And Accounts](./explanations/keys_accounts.md) 28 | - [Chainspecs](./explanations/chainspecs.md) 29 | - [References](./references/index.md) 30 | -------------------------------------------------------------------------------- /src/_site/main.js: -------------------------------------------------------------------------------- 1 | window.addEventListener("load", () => { 2 | const scrollbox = document.querySelector(".sidebar-scrollbox"); 3 | scrollbox.innerHTML = `
Version:
${scrollbox.innerHTML}`; 4 | const currentVersion = window.HOOKSHOT_VERSION || "latest"; 5 | 6 | const selectElement = document.createElement("select"); 7 | 8 | fetch("https://api.github.com/repos/matrix-org/matrix-hookshot/releases", { 9 | cache: "force-cache", 10 | }) 11 | .then((res) => res.json()) 12 | .then((releases) => { 13 | selectElement.innerHTML = ""; 14 | for (const version of [ 15 | "latest", 16 | ...releases.map((r) => r.tag_name).filter((s) => s !== "0.1.0"), 17 | ]) { 18 | const option = document.createElement("option"); 19 | option.innerHTML = version; 20 | selectElement.add(option); 21 | if (currentVersion === version) { 22 | option.setAttribute("selected", ""); 23 | } 24 | } 25 | }) 26 | .catch((ex) => { 27 | console.error("Failed to fetch version data", ex); 28 | }); 29 | 30 | const option = document.createElement("option"); 31 | option.innerHTML = "loading..."; 32 | selectElement.add(option); 33 | 34 | selectElement.addEventListener("change", (event) => { 35 | const path = [ 36 | ...window.location.pathname.split("/").slice(0, 2), 37 | event.target.value, 38 | ...window.location.pathname.split("/").slice(3), 39 | ].join("/"); 40 | window.location = `${window.location.origin}${path}`; 41 | }); 42 | 43 | document.querySelector(".version-box").appendChild(selectElement); 44 | }); 45 | -------------------------------------------------------------------------------- /src/_site/style.css: -------------------------------------------------------------------------------- 1 | .notice { 2 | color: black; 3 | border: 2px solid #0098d4; 4 | border-left-width: 2px; 5 | border-left-width: 5px; 6 | background: #e5f5fb; 7 | padding: 10px 20px; 8 | } 9 | 10 | .notice::before { 11 | content: "INFO: "; 12 | font-weight: 700; 13 | } 14 | 15 | .warning { 16 | color: black; 17 | border: 2px solid #dda02f; 18 | border-left-width: 2px; 19 | border-left-width: 5px; 20 | background: #fdcd74; 21 | padding: 10px 20px; 22 | } 23 | 24 | .warning::before { 25 | content: "WARNING: "; 26 | font-weight: 700; 27 | } 28 | 29 | /* icons for headers */ 30 | 31 | .chapter > li:nth-child(3) > ol:nth-child(1) > li:nth-child(2) strong:after { 32 | content: " " url("/matrix-hookshot/latest/icons/feeds.png"); 33 | } 34 | 35 | .chapter > li:nth-child(3) > ol:nth-child(1) > li:nth-child(3) strong:after { 36 | content: " " url("/matrix-hookshot/latest/icons/figma.png"); 37 | } 38 | 39 | .chapter > li:nth-child(3) > ol:nth-child(1) > li:nth-child(4) strong:after { 40 | content: " " url("/matrix-hookshot/latest/icons/github.png"); 41 | } 42 | 43 | .chapter > li:nth-child(3) > ol:nth-child(1) > li:nth-child(5) strong:after { 44 | content: " " url("/matrix-hookshot/latest/icons/gitlab.png"); 45 | } 46 | 47 | .chapter > li:nth-child(3) > ol:nth-child(1) > li:nth-child(6) strong:after { 48 | content: " " url("/matrix-hookshot/latest/icons/jira.png"); 49 | } 50 | 51 | .chapter > li:nth-child(3) > ol:nth-child(1) > li:nth-child(7) strong:after { 52 | content: " " url("/matrix-hookshot/latest/icons/webhooks.png"); 53 | } 54 | -------------------------------------------------------------------------------- /src/_site/version.js: -------------------------------------------------------------------------------- 1 | // This is modified by the build script 2 | window.HOOKSHOT_VERSION = "latest"; 3 | -------------------------------------------------------------------------------- /src/deployments/example.md: -------------------------------------------------------------------------------- 1 | # Example Deployments 2 | 3 | ## Development Testnet 4 | 5 | Below is an example configuration of a private or public testnet. Where one provider is used and hosts are spread over two locations/zones within that provider. 6 | 7 | | Function | Provider(s) | Count | Locations | 8 | | ------------- | ----------- | ----- | --------- | 9 | | Bootnodes | 1 | 2 | 2 | 10 | | Validator | 1 | 4 | 2 | 11 | | RPC | 1 | 2 | 2 | 12 | | Load Balancer | 1 | 1 | 2 | 13 | 14 | ## Parachain Network 15 | 16 | Below is a minimal configuration example for a production parachain. This example uses two providers with four locations, which should all be well physically distributed. Adding more locations within the existing providers and a third provider is recommended for a highly available configuration. 17 | 18 | | Function | Provider(s) | Count | Locations | 19 | | ------------- | ----------- | ----- | --------- | 20 | | Bootnodes | 2 | 4 | 4 | 21 | | Validator | 2 | 8 | 4 | 22 | | RPC | 2 | 8 | 4 | 23 | | Load Balancer | 2 | 1 | 2 | 24 | -------------------------------------------------------------------------------- /src/deployments/index.md: -------------------------------------------------------------------------------- 1 | # Deployments 2 | 3 | This section describes the various types of deployments and options used for each. 4 | -------------------------------------------------------------------------------- /src/deployments/options.md: -------------------------------------------------------------------------------- 1 | # Special Options Per Host Type 2 | 3 | | Type | Function | 4 | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | 5 | | Validator | Should at least be running with the `--validator` flag to enable block validation. Also keys should have been injected or the RPC `author_rotateKeys` called. | 6 | | Collator | Should at least be running with the `--collator` flag to enable parachain collation. | 7 | | Bootnode | A node with a static key file so the p2p public address is always the same. Store this private key in a file and use the option: `--node-key-file /path/to/file` | 8 | | RPC Node | Use these options to allow 5000 public RPC/WS connections: `--unsafe-ws-external --rpc-methods Safe --rpc-cors ‘*’ --ws-max-connections 5000` | 9 | | Archive Node | Use `-–pruning=archive` to not prune any block history | 10 | | Full Node | N/A | 11 | 12 | ## Parachain Specifics 13 | 14 | When running a parachain then you will need two sets of arguments, one for the relay chain and one for the parachain. Used in the format: 15 | 16 | ```bash 17 | ./statemine $PARACHAIN_OPTIONS -- $RELAYCHAIN_OPTIONS 18 | ``` 19 | 20 | A real life example of this while executing as a statemine collator would be: 21 | 22 | ```bash 23 | ./statemine --chain statemine --in-peers 25 --out-peers 25 --db-cache 512 --pruning=1000 --unsafe-pruning -- --chain kusama -db-cache 512 --pruning=1000 --wasm-execution Compiled 24 | ``` 25 | -------------------------------------------------------------------------------- /src/deployments/parachain-node-diagram.drawio.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
10 |
11 |
12 | Relaychain 13 |
14 | Network 15 |
16 |
17 |
18 | 19 | 20 | Relaychain... 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 |
29 |
30 |
31 | Parachain 32 |
33 | Network 34 |
35 |
36 |
37 | 38 | 39 | Parachain... 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 |
48 |
49 |
50 | Parachain Collator 51 |
52 |
53 |
54 |
55 |
56 |
57 |
58 | 59 | 60 | Parachain Collator... 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 |
69 |
70 |
71 | 30333 72 |
73 |
74 |
75 | 76 | 77 | 30333 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 |
86 |
87 |
88 | Parachain 89 |
90 | RPC Node 91 |
92 |
93 |
94 | 95 | 96 | Parachain... 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 |
105 |
106 |
107 | 30333 108 |
109 |
110 |
111 | 112 | 113 | 30333 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 |
124 |
125 |
126 | P2P 127 |
128 |
129 |
130 | 131 | 132 | P2P 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 |
141 |
142 |
143 | 9944 144 |
145 |
146 |
147 | 148 | 149 | 9944 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 |
159 |
160 |
161 | Public RPC 162 |
163 | 164 | (HTTP/WS) 165 | 166 |
167 |
168 |
169 | 170 | 171 | Public RPC... 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 |
180 |
181 |
182 | 30334 183 |
184 |
185 |
186 | 187 | 188 | 30334 189 | 190 | 191 | 192 | 193 | 194 | 195 | 196 |
197 |
198 |
199 | Relaychain Validator 200 |
201 |
202 |
203 |
204 |
205 |
206 |
207 |
208 |
209 |
210 |
211 | 212 | 213 | Relaychain Validator... 214 | 215 | 216 | 217 | 218 | 219 | 220 | 221 |
222 |
223 |
224 | 225 | Para Block 226 |
227 | Validation 228 | 229 |
230 |
231 |
232 | 233 | 234 | Para Block... 235 | 236 | 237 | 238 | 239 | 240 | 241 | 242 | 243 |
244 |
245 |
246 | 247 |
248 | Para 249 |
250 | DB 251 | 252 |
253 |
254 |
255 | 256 | 257 | Para... 258 | 259 | 260 | 261 | 262 | 263 | 264 | 265 | 266 |
267 |
268 |
269 | 270 |
271 | Pruned 272 |
273 | DB 274 | 275 |
276 |
277 |
278 | 279 | 280 | Pruned... 281 | 282 | 283 | 284 | 285 | 286 | 287 | 288 | 289 | 290 |
291 |
292 |
293 | Aura Key 294 |
295 |
296 |
297 | 298 | 299 | Aura K... 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 |
308 |
309 |
310 | 311 | Block 312 |
313 | Production 314 | 315 |
316 |
317 |
318 | 319 | 320 | Block... 321 | 322 | 323 | 324 | 325 | 326 | 327 | 328 |
329 |
330 |
331 | 30334 332 |
333 |
334 |
335 | 336 | 337 | 30334 338 | 339 | 340 | 341 | 342 | 343 | 344 | 345 | 346 | 347 |
348 |
349 |
350 | P2P 351 |
352 |
353 |
354 | 355 | 356 | P2P 357 | 358 | 359 | 360 | 361 | 362 | 363 | 364 | 365 |
366 |
367 |
368 | 369 |
370 | Para 371 |
372 | DB 373 | 374 |
375 |
376 |
377 | 378 | 379 | Para... 380 | 381 | 382 | 383 | 384 | 385 | 386 | 387 |
388 |
389 |
390 | Open 391 |
392 | Port 393 |
394 |
395 |
396 | 397 | 398 | Open... 399 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 |
408 |
409 |
410 | 411 |
412 | Archive 413 |
414 | DB 415 | 416 |
417 |
418 |
419 | 420 | 421 | Archive... 422 | 423 | 424 | 425 | 426 | 427 | 428 | 429 | 430 |
431 |
432 |
433 | 434 |
435 | Relay 436 |
437 | DB 438 | 439 |
440 |
441 |
442 | 443 | 444 | Relay... 445 | 446 | 447 | 448 | 449 | 450 | 451 | 452 | 453 | 454 |
455 |
456 |
457 | Protocol Key 458 |
459 |
460 |
461 | 462 | 463 | Protoc... 464 | 465 | 466 | 467 | 468 | 469 | 470 | 471 |
472 |
473 |
474 | Parachain 475 |
476 | Boot Node 477 |
478 |
479 |
480 | 481 | 482 | Parachain... 483 | 484 | 485 | 486 | 487 | 488 | 489 | 490 |
491 |
492 |
493 | 30333 494 |
495 |
496 |
497 | 498 | 499 | 30333 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 |
509 |
510 |
511 | 512 | /dns/bootnode.example.com 513 |
514 | /tcp/30333/p2p/<ADDRESS> 515 | 516 |
517 |
518 |
519 | 520 | 521 | /dns/bootnode.example.com... 522 | 523 | 524 | 525 | 526 | 527 | 528 | 529 | 530 | 531 |
532 |
533 |
534 | P2P 535 |
536 |
537 |
538 | 539 | 540 | P2P 541 | 542 | 543 | 544 | 545 | 546 | 547 | 548 | 549 | 550 |
551 |
552 |
553 | Babe 554 |
555 |
556 |
557 | 558 | 559 | Babe 560 | 561 | 562 | 563 | 564 | 565 | 566 | 567 | 568 | 569 |
570 |
571 |
572 | Grandpa 573 |
574 |
575 |
576 | 577 | 578 | Grandpa 579 | 580 | 581 | 582 | 583 | 584 | 585 | 586 | 587 |
588 |
589 |
590 | 591 |
592 | Relay 593 |
594 | DB 595 | 596 |
597 |
598 |
599 | 600 | 601 | Relay... 602 | 603 | 604 | 605 | 606 | 607 | 608 | 609 |
610 |
611 |
612 | 613 | Symbols used 614 | 615 |
616 |
617 |
618 | 619 | 620 | Symbols used 621 | 622 | 623 | 624 | 625 | 626 | 627 | 628 | 629 |
630 |
631 |
632 | 633 |
634 | Para 635 |
636 | DB 637 | 638 |
639 |
640 |
641 | 642 | 643 | Para... 644 | 645 | 646 | 647 | 648 | 649 | 650 | 651 | 652 | Text is not SVG - cannot display 653 | 654 | 655 | 656 | -------------------------------------------------------------------------------- /src/deployments/roles.md: -------------------------------------------------------------------------------- 1 | # Blockchain Node Roles 2 | 3 | A non exhaustive list of some common roles assumed by nodes: 4 | 5 | | Role | Description | 6 | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 7 | | Validator | Secures the Relay Chain by staking DOT, validating proofs from collators on parachains and voting on consensus along with other validators. | 8 | | Collator | Maintains a parachain by collecting parachain transactions and producing state transition proofs for the validators. | 9 | | Bootnode | A node with a static address and p2p public key, used to bootstrap a node onto the network’s distributed hash table and find peers. | 10 | | RPC Node | Expose an RPC interface over http or websocket for the relay chain or parachain and allow users to read the blockchain state and submit transactions (extrinsics). There are often multiple RPC nodes behind a load balancer. | 11 | 12 | Additionally, we also usually distinguish types of nodes: 13 | 14 | | Type | Description | 15 | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 16 | | Full Node | A node which is syncing the relay chain or parachain to the current best block. It can make use of database pruning to reduce its disk usage. | 17 | | Archive Node | A full node which has a complete database starting all the way from the genesis block. 18 | | Light Node | Also called light client, can connect to a chain network but does not require to have full copy of the entire blockchain | 19 | 20 | ## Simplified Diagram of the Parachain Network architecture 21 | 22 | The diagram below illustrate how different nodes play different roles in the network by having different configuration. 23 | 24 | ![parachain node diagram](./parachain-node-diagram.drawio.svg) 25 | 26 | - Bootnodes expose their P2P port behind an easy to find IP or DNS address. 27 | - RPC nodes expose their RPC endpoint publicly. 28 | - Collators sign blocks and propose them for validation to the Relaychain validators 29 | - We can adjust the database pruning (archive or pruned) depending on the node role. 30 | 31 | ## Downsides of deploying nodes without clear role separation 32 | 33 | Although, it is possible for a single node to assume multiple roles (collator, RPC, bootnode), robust network deployments are composed of multiple nodes of each types to ensure reliability. 34 | 35 | For example, if a collator node also serves as an RPC node, receiving increased user traffic might overload the node and bring down block production. To prevent this from happening, it is possible to set up several dedicated RPC nodes behind a load balancer. Similarly, setting up additional collators in your network will allows downtime of fraction of the collator set without slowing down block production. 36 | -------------------------------------------------------------------------------- /src/deployments/targets.md: -------------------------------------------------------------------------------- 1 | # Deployment Targets 2 | 3 | A non-exhaustive list of some common deployment targets: 4 | 5 | | Type | Description | 6 | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 7 | | Physical Server | Usually a rack mounted server sitting in a data center. | 8 | | Virtual Machine | A virtual machine hosted by one of many cloud providers or self-hosted onsite. | 9 | | Kubernetes | A container orchestration engine to host your blockchain instances. This option is only recommended if you already have prior experience with Kubernetes, especially in production environments. | 10 | | Local Container | An instance running on a local container engine (e.g. containerd, docker, Podman). | 11 | -------------------------------------------------------------------------------- /src/explanations/chainspecs.md: -------------------------------------------------------------------------------- 1 | # Custom Chain - Chainspecs 2 | 3 | This section will explain what is required to build a custom chain spec for your own network. 4 | For more in depth explanations on how chainspecs works internally, refer to the [Polkadot-sdk Chainspec docs](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/chain_spec_genesis/index.html) 5 | 6 | ## Create Chain Spec with the node binary 7 | 8 | You can create a plain chainspec for your network with: 9 | 10 | ```bash 11 | node build-spec –chain chain-name --disable-default-bootnode > custom-chainspec.json 12 | ``` 13 | 14 | **Important Fields**: 15 | 16 | | Field | Purpose | 17 | |------------------------|----------------------------------------------------------------------| 18 | | Name | Name of the network | 19 | | id | Id of network, also used for the filesystem path | 20 | | bootNodes | List of multiaddr’s of bootnodes for the network | 21 | | protocolId | A unique identifier for the protocol | 22 | | para_id | (Parachains only) numerical ID of the parachain slot | 23 | | relay_chain | (Parachains only) Id of the relaychain to connect to | 24 | | genesis.runtimeGenesis | (Plain chainspec only) Configuration of the genesis runtime | 25 | | genesis.raw | (Raw chainspec only) Serialization of the raw of the genesis storage | 26 | 27 | Once the values have been updated this chainspec should be converted in raw format using the command: 28 | 29 | ```bash 30 | node build-spec –chain custom-chainspec.json –raw > custom-chainspec-raw.json 31 | ``` 32 | 33 | ## Using the chain-spec-builder 34 | 35 | The chain-spec builder is a utility that can create a chainspec from a runtime wasm. The tool's linux binary can be downloaded from the [polkadot-sdk release page](https://github.com/paritytech/polkadot-sdk/releases) or built from sources in [polkadot-sdk/substrate/bin/utils/chain-spec-builder](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/bin/utils/chain-spec-builder). 36 | 37 | ### Create a genesis.json file from presets 38 | 39 | Runtimes can have config presets which are examples of valid genesis configuration files that can be edited for customizing chainspecs. 40 | 41 | #### List the available presets of a runtime 42 | 43 | $ chain-spec-builder list-presets --runtime-wasm-path rococo_runtime-v1015000.compact.compressed.wasm 44 | 45 | ```json 46 | { 47 | "presets": [ 48 | "local_testnet", 49 | "development", 50 | "staging_testnet", 51 | "wococo_local_testnet", 52 | "versi_local_testnet" 53 | ] 54 | } 55 | ``` 56 | 57 | Unfortunately, not all existing runtimes have embedded presets, if those are not available, you should ask your chain developers to move their genesis config presets from the node binary to the runtime (see eg. [polkadot-sdk#4749](https://github.com/paritytech/polkadot-sdk/pull/4739)). 58 | 59 | 60 | #### Export a config preset from a runtime file 61 | 62 | $ chain-spec-builder display-preset --runtime-wasm-path rococo_runtime-v1015000.compact.compressed.wasm --preset-name staging_testnet > rococo-genesis.json 63 | 64 | 65 |
66 | rococo-genesis.json 67 | 68 | { 69 | "babe": { 70 | "epochConfig": { 71 | "allowed_slots": "PrimaryAndSecondaryVRFSlots", 72 | "c": [ 73 | 1, 74 | 4 75 | ] 76 | } 77 | }, 78 | "balances": { 79 | "balances": [ 80 | [ 81 | "5DwBmEFPXRESyEam5SsQF1zbWSCn2kCjyLW51hJHXe9vW4xs", 82 | 1000000000000000000 83 | ], 84 | [ 85 | "5EHZkbp22djdbuMFH9qt1DVzSCvqi3zWpj6DAYfANa828oei", 86 | 100000000000000 87 | ], 88 | [ 89 | "5DvH8oEjQPYhzCoQVo7WDU91qmQfLZvxe9wJcrojmJKebCmG", 90 | 100000000000000 91 | ], 92 | [ 93 | "5FPMzsezo1PRxYbVpJMWK7HNbR2kUxidsAAxH4BosHa4wd6S", 94 | 100000000000000 95 | ], 96 | [ 97 | "5DMNx7RoX6d7JQ38NEM7DWRcW2THu92LBYZEWvBRhJeqcWgR", 98 | 100000000000000 99 | ], 100 | [ 101 | "5C8AL1Zb4bVazgT3EgDxFgcow1L4SJjVu44XcLC9CrYqFN4N", 102 | 100000000000000 103 | ], 104 | [ 105 | "5C8XbDXdMNKJrZSrQURwVCxdNdk8AzG6xgLggbzuA399bBBF", 106 | 100000000000000 107 | ], 108 | [ 109 | "5HinEonzr8MywkqedcpsmwpxKje2jqr9miEwuzyFXEBCvVXM", 110 | 100000000000000 111 | ], 112 | [ 113 | "5Ey3NQ3dfabaDc16NUv7wRLsFCMDFJSqZFzKVycAsWuUC6Di", 114 | 100000000000000 115 | ] 116 | ] 117 | }, 118 | "configuration": { 119 | "config": { 120 | "approval_voting_params": { 121 | "max_approval_coalesce_count": 1 122 | }, 123 | "async_backing_params": { 124 | "allowed_ancestry_len": 2, 125 | "max_candidate_depth": 3 126 | }, 127 | "code_retention_period": 1200, 128 | "dispute_period": 6, 129 | "dispute_post_conclusion_acceptance_period": 100, 130 | "executor_params": [], 131 | "hrmp_channel_max_capacity": 8, 132 | "hrmp_channel_max_message_size": 1048576, 133 | "hrmp_channel_max_total_size": 8192, 134 | "hrmp_max_message_num_per_candidate": 5, 135 | "hrmp_max_parachain_inbound_channels": 4, 136 | "hrmp_max_parachain_outbound_channels": 4, 137 | "hrmp_recipient_deposit": 0, 138 | "hrmp_sender_deposit": 0, 139 | "max_code_size": 3145728, 140 | "max_downward_message_size": 1048576, 141 | "max_head_data_size": 32768, 142 | "max_pov_size": 5242880, 143 | "max_upward_message_num_per_candidate": 5, 144 | "max_upward_message_size": 51200, 145 | "max_upward_queue_count": 8, 146 | "max_upward_queue_size": 1048576, 147 | "max_validators": null, 148 | "minimum_backing_votes": 2, 149 | "minimum_validation_upgrade_delay": 5, 150 | "n_delay_tranches": 25, 151 | "needed_approvals": 2, 152 | "no_show_slots": 2, 153 | "node_features": { 154 | "bits": 8, 155 | "data": [ 156 | 2 157 | ], 158 | "head": { 159 | "index": 0, 160 | "width": 8 161 | }, 162 | "order": "bitvec::order::Lsb0" 163 | }, 164 | "pvf_voting_ttl": 2, 165 | "relay_vrf_modulo_samples": 2, 166 | "scheduler_params": { 167 | "group_rotation_frequency": 20, 168 | "lookahead": 2, 169 | "max_availability_timeouts": 0, 170 | "max_validators_per_core": null, 171 | "num_cores": 0, 172 | "on_demand_base_fee": 10000000, 173 | "on_demand_fee_variability": 30000000, 174 | "on_demand_queue_max_size": 10000, 175 | "on_demand_target_queue_utilization": 250000000, 176 | "paras_availability_period": 4, 177 | "ttl": 5 178 | }, 179 | "validation_upgrade_cooldown": 2, 180 | "validation_upgrade_delay": 2, 181 | "zeroth_delay_tranche_width": 0 182 | } 183 | }, 184 | "registrar": { 185 | "nextFreeParaId": 2000 186 | }, 187 | "session": { 188 | "keys": [ 189 | [ 190 | "5EHZkbp22djdbuMFH9qt1DVzSCvqi3zWpj6DAYfANa828oei", 191 | "5EHZkbp22djdbuMFH9qt1DVzSCvqi3zWpj6DAYfANa828oei", 192 | { 193 | "authority_discovery": "5HbSgM72xVuscsopsdeG3sCSCYdAeM1Tay9p79N6ky6vwDGq", 194 | "babe": "5Fh6rDpMDhM363o1Z3Y9twtaCPfizGQWCi55BSykTQjGbP7H", 195 | "beefy": "KWAWRuYGuB7eAXWBsb7ZtaA267AUABJCP45vA7T61bNKG3zMc", 196 | "grandpa": "5CPd3zoV9Aaah4xWucuDivMHJ2nEEmpdi864nPTiyRZp4t87", 197 | "para_assignment": "5HQdwiDh8Qtd5dSNWajNYpwDvoyNWWA16Y43aEkCNactFc2b", 198 | "para_validator": "5CP6oGfwqbEfML8efqm1tCZsUgRsJztp9L8ZkEUxA16W8PPz" 199 | } 200 | ], 201 | [ 202 | "5DvH8oEjQPYhzCoQVo7WDU91qmQfLZvxe9wJcrojmJKebCmG", 203 | "5DvH8oEjQPYhzCoQVo7WDU91qmQfLZvxe9wJcrojmJKebCmG", 204 | { 205 | "authority_discovery": "5HeXbwb5PxtcRoopPZTp5CQun38atn2UudQ8p2AxR5BzoaXw", 206 | "babe": "5DLjSUfqZVNAADbwYLgRvHvdzXypiV1DAEaDMjcESKTcqMoM", 207 | "beefy": "KWCXxi2nesB7EUaPMr5oExVcaJ5AmN5adHtWdXeqoEhmMcTK7", 208 | "grandpa": "5HnDVBN9mD6mXyx8oryhDbJtezwNSj1VRXgLoYCBA6uEkiao", 209 | "para_assignment": "5ES3fw5X4bndSgLNmtPfSbM2J1kLqApVB2CCLS4CBpM1UxUZ", 210 | "para_validator": "5EPEWRecy2ApL5n18n3aHyU1956zXTRqaJpzDa9DoqiggNwF" 211 | } 212 | ], 213 | [ 214 | "5FPMzsezo1PRxYbVpJMWK7HNbR2kUxidsAAxH4BosHa4wd6S", 215 | "5FPMzsezo1PRxYbVpJMWK7HNbR2kUxidsAAxH4BosHa4wd6S", 216 | { 217 | "authority_discovery": "5D4r6YaB6F7A7nvMRHNFNF6zrR9g39bqDJFenrcaFmTCRwfa", 218 | "babe": "5GpZhzAVg7SAtzLvaAC777pjquPEcNy1FbNUAG2nZvhmd6eY", 219 | "beefy": "KWCGCQqZsnEB4jitvZstHq9dxJE4unuAga5naKmPUUs1oVya8", 220 | "grandpa": "5HAes2RQYPbYKbLBfKb88f4zoXv6pPA6Ke8CjN7dob3GpmSP", 221 | "para_assignment": "5CtK7JHv3h6UQZ44y54skxdwSVBRtuxwPE1FYm7UZVhg8rJV", 222 | "para_validator": "5FtAGDZYJKXkhVhAxCQrXmaP7EE2mGbBMfmKDHjfYDgq2BiU" 223 | } 224 | ], 225 | [ 226 | "5DMNx7RoX6d7JQ38NEM7DWRcW2THu92LBYZEWvBRhJeqcWgR", 227 | "5DMNx7RoX6d7JQ38NEM7DWRcW2THu92LBYZEWvBRhJeqcWgR", 228 | { 229 | "authority_discovery": "5CtgRR74VypK4h154s369abs78hDUxZSJqcbWsfXvsjcHJNA", 230 | "babe": "5EjkyPCzR2SjhDZq8f7ufsw6TfkvgNRepjCRQFc4TcdXdaB1", 231 | "beefy": "KW8tZu7Cf6dTjGHR6SwQcoAry4LUVCTq3pzfUNSketjYc8NPC", 232 | "grandpa": "5DJV3zCBTJBLGNDCcdWrYxWDacSz84goGTa4pFeKVvehEBte", 233 | "para_assignment": "5F1FZWZSj3JyTLs8sRBxU6QWyGLSL9BMRtmSKDmVEoiKFxSP", 234 | "para_validator": "5F9FsRjpecP9GonktmtFL3kjqNAMKjHVFjyjRdTPa4hbQRZA" 235 | } 236 | ], 237 | [ 238 | "5C8AL1Zb4bVazgT3EgDxFgcow1L4SJjVu44XcLC9CrYqFN4N", 239 | "5C8AL1Zb4bVazgT3EgDxFgcow1L4SJjVu44XcLC9CrYqFN4N", 240 | { 241 | "authority_discovery": "5DABsdQCDUGuhzVGWe5xXzYQ9rtrVxRygW7RXf9Tsjsw1aGJ", 242 | "babe": "5Et3tfbVf1ByFThNAuUq5pBssdaPPskip5yob5GNyUFojXC7", 243 | "beefy": "KW8bmi1qiPmp5x2PAfqBeQ8MdAGWDXo7fYeAAB92oWgXdvXmL", 244 | "grandpa": "5EX1JBghGbQqWohTPU6msR9qZ2nYPhK9r3RTQ2oD1K8TCxaG", 245 | "para_assignment": "5CaZuueRVpMATZG4hkcrgDoF4WGixuz7zu83jeBdY3bgWGaG", 246 | "para_validator": "5EUNaBpX9mJgcmLQHyG5Pkms6tbDiKuLbeTEJS924Js9cA1N" 247 | } 248 | ], 249 | [ 250 | "5C8XbDXdMNKJrZSrQURwVCxdNdk8AzG6xgLggbzuA399bBBF", 251 | "5C8XbDXdMNKJrZSrQURwVCxdNdk8AzG6xgLggbzuA399bBBF", 252 | { 253 | "authority_discovery": "5CZdFnyzZvKetZTeUwj5APAYskVJe4QFiTezo5dQNsrnehGd", 254 | "babe": "5GHWB8ZDzegLcMW7Gdd1BS6WHVwDdStfkkE4G7KjPjZNJBtD", 255 | "beefy": "KW2vnN5A1F59icBUNrF3gpcTdDMb8pvYPVACctkGHkdAW3oDB", 256 | "grandpa": "5GzDPGbUM9uH52ZEwydasTj8edokGUJ7vEpoFWp9FE1YNuFB", 257 | "para_assignment": "5DnsSy8a8pfE2aFjKBDtKw7WM1V4nfE5sLzP15MNTka53GqS", 258 | "para_validator": "5CmLCFeSurRXXtwMmLcVo7sdJ9EqDguvJbuCYDcHkr3cpqyE" 259 | } 260 | ], 261 | [ 262 | "5HinEonzr8MywkqedcpsmwpxKje2jqr9miEwuzyFXEBCvVXM", 263 | "5HinEonzr8MywkqedcpsmwpxKje2jqr9miEwuzyFXEBCvVXM", 264 | { 265 | "authority_discovery": "5ELv74v7QcsS6FdzvG4vL2NnYDGWmRnJUSMKYwdyJD7Xcdi7", 266 | "babe": "5EeCsC58XgJ1DFaoYA1WktEpP27jvwGpKdxPMFjicpLeYu96", 267 | "beefy": "KWA93sGFQ4a2iMR9DGQt7iQj3NZwKW8mWDZU6gZzU6jYubBMX", 268 | "grandpa": "5DnEySxbnppWEyN8cCLqvGjAorGdLRg2VmkY96dbJ1LHFK8N", 269 | "para_assignment": "5HjRTLWcQjZzN3JDvaj1UzjNSayg5ZD9ZGWMstaL7Ab2jjAa", 270 | "para_validator": "5CAC278tFCHAeHYqE51FTWYxHmeLcENSS1RG77EFRTvPZMJT" 271 | } 272 | ], 273 | [ 274 | "5Ey3NQ3dfabaDc16NUv7wRLsFCMDFJSqZFzKVycAsWuUC6Di", 275 | "5Ey3NQ3dfabaDc16NUv7wRLsFCMDFJSqZFzKVycAsWuUC6Di", 276 | { 277 | "authority_discovery": "5DqAvikdpfRdk5rR35ZobZhqaC5bJXZcEuvzGtexAZP1hU3T", 278 | "babe": "5H168nKX2Yrfo3bxj7rkcg25326Uv3CCCnKUGK6uHdKMdPt8", 279 | "beefy": "KW54aj4HK5xHt3eqKqLuPRMDY8kRi4VgKycb3Uq7Bu6fQxqwA", 280 | "grandpa": "5DrA2fZdzmNqT5j6DXNwVxPBjDV9jhkAqvjt6Us3bQHKy3cF", 281 | "para_assignment": "5DhDcHqwxoes5s89AyudGMjtZXx1nEgrk5P45X88oSTR3iyx", 282 | "para_validator": "5Gx6YeNhynqn8qkda9QKpc9S7oDr4sBrfAu516d3sPpEt26F" 283 | } 284 | ] 285 | ] 286 | }, 287 | "sudo": { 288 | "key": "5DwBmEFPXRESyEam5SsQF1zbWSCn2kCjyLW51hJHXe9vW4xs" 289 | } 290 | } 291 | 292 |
293 | 294 | 295 | ### Create a chain-spec from a runtime wasm file 296 | 297 | 298 | ```bash 299 | chain-spec-builder -c chainspec.json create -n "Test Chain" -i test-chain -t live -r runtime.wasm patch genesis.json 300 | ``` 301 | 302 | 303 | ### Verify a chain-spec file 304 | 305 | 306 | ```bash 307 | chain-spec-builder verify chainspec.json 308 | ``` 309 | 310 | ### Convert a plain chain-spec to raw 311 | 312 | ```bash 313 | chain-spec-builder convert-to-raw chainspec.json > chainspec.raw.json 314 | ``` -------------------------------------------------------------------------------- /src/explanations/index.md: -------------------------------------------------------------------------------- 1 | # Explanations 2 | 3 | ## General Approach to Infrastructure 4 | 5 | It is highly recommended that projects deploying networks have an infrastructure as code mindset. The infrastructure components in deployments should be written in code and put in a version control system. 6 | 7 | This ensures that: 8 | 9 | - Your Infrastructure is in a known state 10 | - Version control is available to see changes and enforce reviews etc... 11 | - Rolling back is made very easy 12 | - There are no manual actions required to redeploy 13 | 14 | ![workflow](../images/3osxC7.png) 15 | 16 | ## General Approach to Security 17 | 18 | One of the main desired properties of a blockchain is security, so having a very ‘secure by default’ approach to your infrastructure should always be in the forefront of your mind when deploying new networks. 19 | 20 | On the infrastructure side, having strict rules and blocking any non-required communication is just a starting point. Other things that should be considered are things like log monitoring, bastion hosts being required for access, 2FA for ssh etc… 21 | 22 | On the chain operations side, there are two very useful concepts to increase your security. 23 | 24 | First is using cold / warm / hot keys, so that the compromise of say a session key would not lead to any funds being stolen. Also using multisig accounts on offline devices can greatly help security and also give an on-chain audit trail of all actions, allows for alerting for any onchain actions etc... 25 | 26 | ![key stages](../images/AEEVr6.png) 27 | 28 | Proxy accounts also let you limit the permission that an account or multisig account has on a particular target account (e.g. only staking functions can be executed by the staking controller multisig account and require 3 of 5 people to approve). 29 | -------------------------------------------------------------------------------- /src/explanations/keys_accounts.md: -------------------------------------------------------------------------------- 1 | # Keys And Accounts 2 | 3 | This page will describe some basic information on keys and accounts. For a more general and detailed explanation see [learn accounts](https://wiki.polkadot.network/docs/learn-accounts) on the polkadot wiki page. 4 | 5 | ## Encryption Schemes 6 | 7 | | Name | Type | 8 | | ------- | ---------------------------------------------------------------------------- | 9 | | ed25519 | The vanilla ed25519 implementation using Schnorr signatures. | 10 | | sr25519 | The Schnorrkel/Ristretto sr25519 variant using Schnorr signatures. (default) | 11 | | ecdsa | ECDSA signatures on secp256k1 | 12 | 13 | ## Session Key Types 14 | 15 | | Name | Type | 16 | |---------------------| ------- | 17 | | grandpa | ed25519 | 18 | | authority_discovery | sr25519 | 19 | | aura | sr25519 | 20 | | babe | sr25519 | 21 | | para_validator | sr25519 | 22 | | para_assignment | sr25519 | 23 | | beefy | ecdsa | 24 | 25 | ## Key Generation and Inspection 26 | 27 | You can use `polkadot-parachain keys` or the `subkey` command to generate and inspect keys. 28 | 29 | Two important subcommands are: 30 | 31 | - `generate` Create a new random account and print the private key data or save to a file. 32 | - `inspect` View the account data for an account by passing a secret phrase or seed. 33 | 34 | Some important options are: 35 | 36 | - `--network` specify the network the keys will be used on, default is substrate. 37 | - `--scheme` the scheme for the keys, default is sr25519. 38 | 39 | ## Generate 40 | 41 | ### Create a Random Account Key 42 | 43 | ```bash 44 | $ polkadot-parachain key generate 45 | Secret phrase: test test test test test test test test test test test junk 46 | Network ID: substrate 47 | Secret seed: 0x4ca479f5e0dc0ee04ebcbadb64c220267dad42b8cfa4da1f0874787523b4709c 48 | Public key (hex): 0xd000ac5048ae858aca2e6aa43e00661562a47026fe88ff83992430204a159752 49 | Account ID: 0xd000ac5048ae858aca2e6aa43e00661562a47026fe88ff83992430204a159752 50 | Public key (SS58): 5GmS1wtCfR4tK5SSgnZbVT4kYw5W8NmxmijcsxCQE6oLW6A8 51 | SS58 Address: 5GmS1wtCfR4tK5SSgnZbVT4kYw5W8NmxmijcsxCQE6oLW6A8 52 | ``` 53 | 54 | You can save it to a file using 55 | 56 | ## Inspection 57 | 58 | ### Inspect Created Key 59 | 60 | ```bash 61 | $ polkadot-parachain key inspect "test test test test test test test test test test test junk" 62 | Secret phrase: test test test test test test test test test test test junk 63 | Network ID: substrate 64 | Secret seed: 0x4ca479f5e0dc0ee04ebcbadb64c220267dad42b8cfa4da1f0874787523b4709c 65 | Public key (hex): 0xd000ac5048ae858aca2e6aa43e00661562a47026fe88ff83992430204a159752 66 | Account ID: 0xd000ac5048ae858aca2e6aa43e00661562a47026fe88ff83992430204a159752 67 | Public key (SS58): 5GmS1wtCfR4tK5SSgnZbVT4kYw5W8NmxmijcsxCQE6oLW6A8 68 | SS58 Address: 5GmS1wtCfR4tK5SSgnZbVT4kYw5W8NmxmijcsxCQE6oLW6A8 69 | ``` 70 | 71 | ### Inspect Created Key With Hard Derivation //Stash//0 72 | 73 | ```bash 74 | $ polkadot-parachain key inspect " test test test test test test test test test test test junk//Stash//0" 75 | Secret Key URI ` test test test test test test test test test test test junk//Stash//0` is account: 76 | Network ID: substrate 77 | Secret seed: 0x88f170a1438f83de6c2b845282ebb577dfcaee4c896655e64777ba220b3ad33d 78 | Public key (hex): 0xa2a73aaf576ed83371c92642a80706bf4b007c40f689d649aa7b075833d7242c 79 | Account ID: 0xa2a73aaf576ed83371c92642a80706bf4b007c40f689d649aa7b075833d7242c 80 | Public key (SS58): 5FjyHtMBm7kArqgSX52DAQvZeJ2Tq5sQBwFfSmZ3NWMHs4Be 81 | SS58 Address: 5FjyHtMBm7kArqgSX52DAQvZeJ2Tq5sQBwFfSmZ3NWMHs4Be 82 | ``` 83 | 84 | ## Managing a node session keys 85 | 86 | In Polkadot, **Session Keys** refer to the hot keys set on a node to perform various network operations, such as collating or validating blocks. 87 | 88 | ### Create new session keys on a node via the `author_rotateKeys` RPC method 89 | 90 | On the remote machine hosting the node, you can create new session keys with the following commmand: 91 | 92 | ```bash 93 | curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "author_rotateKeys", "params":[]}' http://localhost:9944 94 | ``` 95 | 96 | The response output will then show the hex-encoded concatenation of the session public keys. This is intended to be submitted on-chain using the [session.setKeys extrinsics](https://wiki.polkadot.network/docs/maintain-guides-how-to-validate-polkadot#submitting-the-setkeys-transaction). 97 | 98 | ### Insert a specific key onto a node keystore via the `author_insertKey` RPC method 99 | 100 | To inject a key via RPC, use the following command: 101 | 102 | ```bash 103 | curl -H "Content-Type: application/json" \ --data '{ "jsonrpc":"2.0", "method":"author_insertKey", "params":["'"${KEY_TYPE}"'", "'"${KEY_SEED}"'"],"id":1 }' http://localhost:9933 104 | ``` 105 | 106 | Set: 107 | * `KEY_TYPE` to a session key type (eg. `babe`, `grandpa`) 108 | * `KEY_SEED` to a secret seed or private key 109 | 110 | ### Insert a specific key onto a node keystore using the node binary 111 | 112 | To inject a key via the node binary, use the following command: 113 | 114 | ```bash 115 | polkadot-parachain key insert -d --key-type ${KEY_TYPE} --scheme ${KEY_SCHEME} --suri ${KEY_FILE} 116 | ``` 117 | 118 | * `KEY_TYPE`: a session key type (eg. `babe`, `grandpa`) 119 | * `KEY_SCHEME`: an encryption scheme (eg. `sr25519`, `ed25519`, `ecdsa`) 120 | * `KEY_FILE`: a plain text file which contains the seed or private key 121 | -------------------------------------------------------------------------------- /src/guides/collator_deployment.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | Collators are members of the network that maintain the parachains they take part in. Collators produce the state transition proof for relay chain validators but also author the blocks for the parachain and pass them to relay chain. There are some requirements that need to be considered prior to becoming a collator candidate including machine, bonding, account, and community requirements. For more info regarding collators, reference [collator section](https://wiki.polkadot.network/docs/learn-collator) on Polkadot wiki page. 3 | 4 | This doc demonstrates how to add new collators to an already running parachain. 5 | 6 | # Hardware Requirements 7 | Make sure your instance has at least the minimum recommended harware requirements: 8 | - CPU: 2 Cores - Intel Xeon E-2386/2388 or Ryzen 9 5950x/5900x 9 | - Memory: 8GB 10 | - Disk: Depending on the chain size - 200GB SSD/nvme 11 | 12 | # Launch the Collator 13 | 1- Generate an Account 14 | 2- Run the Collator 15 | 3- Bind The Account With Collator's Session Keys 16 | 4- Bond Funds 17 | 18 | 19 | ## 1- Create an Account 20 | This account is used to hold funds and submit the extrinsics to bond and register your collator as candidate. 21 | 22 | ``` 23 | > subkey generate 24 | Secret phrase: crane material doll wife text jaguar cross donor crane caught soft permit 25 | Network ID: substrate 26 | Secret seed: 0x79613c5ccb1c8aa9c21e1ddb2fbf65c8e979649cd52cfe041391c9f9d07ec3e9 27 | Public key (hex): 0x4a503b20b3ada9ff3bf985271b5756e650a83ae47e44a7552dc2415ce8060a52 28 | Account ID: 0x4a503b20b3ada9ff3bf985271b5756e650a83ae47e44a7552dc2415ce8060a52 29 | Public key (SS58): 5Dk9EY7iUbjLX6fTDnbFZVGdnN7v2NgQtxj4Y7YjjZXgpCjE 30 | SS58 Address: 5Dk9EY7iUbjLX6fTDnbFZVGdnN7v2NgQtxj4Y7YjjZXgpCjE 31 | ``` 32 | 33 | Store the secret phrase in a secure place. This account will be used on PolkadotJS app to bind you collator session keys to it. 34 | 35 | ## 2- Run the Collator 36 | Now that we have node keys ready, it's time to the collator with the provided chainspec to sync our node with network. Depending on the chain size (both relay and para chains), this will take some time until the node is completely synced with the network: 37 | 38 | ```bash 39 | ./target/release/parachain-node-template --collator \ 40 | --name collator1 \ 41 | --base-path /tmp/parachain/collator1 \ 42 | --chain parachain-chainspec-raw.json \ 43 | --collator \ 44 | --rpc-port 10001 \ 45 | --ws-port 10002 \ 46 | --listen-addr /ip4/0.0.0.0/tcp/10003/ws \ 47 | -- \ 48 | --chain /{PATH_TO_RELAYCHAIN_CHAINSPEC} \ 49 | --port 10004 \ 50 | --ws-port 10005 51 | ``` 52 | 53 | Before jumping to the next steps, you have to wait until your node is fully synchronized: 54 | ```bash 55 | journalctl -f -u shibuya-node -n100 56 | ``` 57 | 58 | ## 3- Bind Your Account with Session Keys 59 | Session keys are a set of cryptographic keys used by collators/validators to securely participate in the consensus mechanism and perform various roles within the network. These keys are essential for ensuring the integrity and security of the blockchain. 60 | 61 | As a collator, you need to link your session keys to your collator account (The account which is created in step 1 and hold the funds). Once linked, the keys are used to identify your collator node. Your collator address will receive the permit to build blocks, but the session keys pass this permit to your node. 62 | 63 | **Author Session Keys** 64 | In order to obtain the session keys, SSH to your node and run the below `curl` command: 65 | ```bash 66 | curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "author_rotateKeys", "params":[]}' http://localhost:9944 67 | ``` 68 | 69 | The result will look like this (you just need to copy the key): 70 | ```bash 71 | {"jsonrpc":"2.0","result":"0x600e6cea49bdeaab301e9e03215c0bcebab3cafa608fe3b8fb6b07a820386048","id":1} 72 | ``` 73 | You can access to the private key generated in this process by reaching the file generated under `chains//keystore`. 74 | 75 | **Set Session Keys** 76 | Go to the Polkadot.js portal and connect to respective network (e.g. Rococo-AssetHub). 77 | Go to Developper > Extrinsic and select your collator account and extrinsic type: session / setKeys 78 | In the `Keys` section paste your session key obtained from the curl command and in the `proof` section enter `0x`. Finally submit the call. 79 | 80 | Note: The proof depends on the session key. For instance if your session key was started with `00x` the proof would be `00x`. 81 | 82 | 83 | ## 4- Bond Funds 84 | Dependig on the parachain, you need a minimum amount of funds to be able to start authoring the blocks. 85 | Go to the Polkadot.js portal: Developer > Extrinsics 86 | Select your collator account and extrinsic type: CollatorSelection / registerAsCandidate 87 | and finally submit the transaction. 88 | 89 | 90 | **Congratulations!** 91 | If you have followed all of these steps, and been selected to be a part of the collator set, you are now running a collator! 92 | Once your collator is active, you will see your name inside Network tab every time you produce a block: 93 | 94 | 95 | 96 | # Kubernetes 97 | If you wish to run the collator on kubernetes environment, there's already a node helm-chart developed by parity that supports collators. 98 | 99 | #### Add Node Helm Chart Repo 100 | ```bash 101 | helm repo add parity https://paritytech.github.io/helm-charts/ 102 | helm -n NAMESPACE upgrade --install RELEASE_NAME -f FILE_NAME.yml parity/node 103 | ``` 104 | 105 | #### Install the node helm chart 106 | Here's an example values file that will be needed to properly deploy the parachain: 107 | ```bash 108 | node: 109 | image: 110 | repository: parity/polkadot-parachain 111 | tag: 1.14.0 112 | node: 113 | chain: asset-hub-polkadot 114 | command: polkadot-parachain 115 | replicas: 2 116 | role: collator 117 | chainData: 118 | database: paritydb 119 | volumeSize: 100Gi 120 | storageClass: ssd-csi 121 | pruning: 1000 122 | chainKeystore: 123 | mountInMemory: 124 | enabled: true 125 | isParachain: true 126 | collatorRelayChain: 127 | chain: polkadot 128 | chainData: 129 | database: paritydb 130 | pruning: 256 131 | storageClass: ssd-csi 132 | volumeSize: 200Gi 133 | chainSnapshot: 134 | enabled: true 135 | method: http-filelist 136 | url: https://snapshots.polkadot.io/polkadot-paritydb-prune 137 | chainPath: polkadot 138 | chainKeystore: 139 | mountInMemory: 140 | enabled: true 141 | perNodeServices: 142 | relayP2pService: 143 | enabled: true 144 | paraP2pService: 145 | enabled: true 146 | port: 30333 147 | apiService: 148 | enabled: true 149 | type: ClusterIP 150 | setPublicAddressToExternalIp: 151 | enabled: true 152 | ``` 153 | -------------------------------------------------------------------------------- /src/guides/index.md: -------------------------------------------------------------------------------- 1 | # How-to Guides 2 | 3 | This section provides useful guides for getting started with Polkadot infrastructure. 4 | -------------------------------------------------------------------------------- /src/guides/parachain_deployment.md: -------------------------------------------------------------------------------- 1 | # Guide: Deploying a Parachain Network 2 | 3 | This guide demonstrates the deployment of a parachain test network composed of 2 collators (nodes authoring blocks) and 1 RPC node. 4 | We are using Paseo as an example, but this approach would work similarly for any Relaychain, whether it is a testnet (Westend, Paseo) or a mainnet (Polkadot, Kusama). 5 | 6 | ## Preparations 7 | 8 | ### Hardware 9 | 10 | For this example network, you will need 3 machines. 11 | The specifications of these machines will depend on your intended usage. For a testnet, medium-sized virtual machines with 2 to 4 cores will suffice. However, for mainnet nodes, it is recommended to follow the ["validator reference hardware" as detailed in the Polkadot Wiki](https://wiki.polkadot.network/docs/maintain-guides-how-to-validate-polkadot#reference-hardware). 12 | 13 | Requirements: 14 | 15 | * The machines should have a public IP and allow network access on their P2P ports (defaults 30333 and 30334) as well as the RPC port for the RPC node (9944 for ws or 443 for wss). 16 | * The machine should have a big enough disk to host the relay-chain pruned database (>100 GB for Paseo) 17 | * You should have obtained SSH access to these machines. 18 | 19 | ### Parachain binary or docker image 20 | 21 | ### Prepare the binary for use with Ansible 22 | 23 | To deploy your network with the [Ansible node role](https://github.com/paritytech/ansible-galaxy/blob/main/roles/node), you will need to have the node binary available from a public URL. 24 | If this binary is not already available for your parachain, you will need to build it yourself using the following command: 25 | 26 | ``` 27 | cargo build --release 28 | ``` 29 | 30 | Then publish the node binary present in `target/releases` somewhere and note down the public URL. One option to do this is to add it as a [GitHub release asset](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository). 31 | In this guide, we will use the `parachain-template-node` that you can get from [paritytech/polkadot-sdk-parachain-template's releases assets](https://github.com/paritytech/polkadot-sdk-parachain-template/releases). 32 | 33 | To deploy system parachain nodes, such as asset-hub and bridge-hub, you should use the `polkadot-parachain` binary published on [https://github.com/paritytech/polkadot-sdk/releases/latest/](https://github.com/paritytech/polkadot-sdk/releases/latest). 34 | 35 | ### Prepare the docker image for use with Kubernetes 36 | 37 | To deploy your network with the [node helm-chart](https://github.com/paritytech/helm-charts/tree/main/charts/node), you will need to have a node docker image published to a public registry. 38 | 39 | ## Generate parachain private keys 40 | 41 | In this section, we will use the [`subkey`](./subkey.md) utility. 42 | 43 | ### Generate static node keys (aka network keys) 44 | 45 | Node keys are used to identify nodes on the P2P network with a unique PeerID. 46 | To ensure this identifier persists across restarts, it is highly recommended to generate a static network key for all nodes. 47 | This practice is particularly important for bootnodes, which have publicly listed addresses that are used by other nodes to bootstrap their connections to the network. 48 | 49 | To generate a static node key: 50 | 51 | ``` 52 | subkey generate-node-key --file node.key 53 | # example output 54 | 12D3KooWExcVYu7Mvjd4kxPVLwN2ZPnZ5NyLZ5ft477wqzfP2q6E # PeerId (hash of public node key) 55 | cat node.key 56 | d5e120e30dfb0eac39b1a6727d81c548e9c6b39ca97e565438a33d87726781a6% # private node key, do not copy the percent sign 57 | ``` 58 | 59 | ### Generate keys for your collators (account+aura keys) 60 | 61 | For parachains using the collatorSelection pallet to manage their collator set, you will need to generate a set of keys for each collator: 62 | 63 | * Collator Account: a regular substrate account 64 | * Aura keys (part of the collator “session keys”) 65 | 66 | In this example, we will use the same seed for both. Use the following command generate a secret seed for each collator: 67 | 68 | ``` 69 | subkey generate 70 | ``` 71 | 72 | You can derive public keys and account IDs from an existing seed by using: 73 | ``` 74 | subkey inspect "" 75 | # example output 76 | Secret Key URI `//Alice` is account: 77 | Network ID: substrate 78 | Secret seed: 0xe5be9a5092b81bca64be81d212e7f2f9eba183bb7a90954f7b76361f6edb5c0a 79 | Public key (hex): 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d 80 | Account ID: 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d 81 | Public key (SS58): 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY 82 | SS58 Address: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY 83 | ``` 84 | 85 | ## Reserve a ParaId on Paseo 86 | 87 | Note: although it is possible to use specific UIs for registering your parachain, this guide only documents how to do it by submitting extrinsics directly through the Polkadot.js Console. 88 | 89 | To get reserve a ParaId for your parachain on Paseo, navigate to the [Polkadot.js Apps interface](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frpc.ibp.network%2Fpaseo#/explorer). 90 | 91 | * Ensure you are connected to the Paseo network by selecting the appropriate RPC endpoint. 92 | * Go to the "Developer" tab and select "Extrinsics". 93 | * Choose `registrar.reserve` from the dropdown menu and execute it with your account. 94 | * Check the included extrinsic result in the block to find your reserved `para_id` and note it down. 95 | 96 | 97 | ## Create your Network Chainspec 98 | 99 | When launching a new parachain network, customizing the chainspec (chain specification) is a crucial step. 100 | 101 | ### Export your runtime file 102 | 103 | First export your runtime file from your node binary (here `--raw` is used to export the output as binary not hex string): 104 | 105 | ``` 106 | parachain-template-node export-genesis-wasm --raw > runtime.wasm 107 | ``` 108 | 109 | If you want to select a specific built-in runtimle of your binary, add `--chain chain-name` to your command. 110 | 111 | ### Prepare your genesis patch config 112 | 113 | Save the following to `genesis.patch.json` (replace keys and configuration with your own): 114 | ```json 115 | { 116 | "balances": { 117 | "balances": [ 118 | [ 119 | "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY", 120 | 1152921504606846976 121 | ], 122 | [ 123 | "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty", 124 | 1152921504606846976 125 | ] 126 | ] 127 | }, 128 | "collatorSelection": { 129 | "candidacyBond": 16000000000, 130 | "invulnerables": [ 131 | "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY", 132 | "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty" 133 | ] 134 | }, 135 | "session": { 136 | "keys": [ 137 | [ 138 | "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY", 139 | "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY", 140 | { 141 | "aura": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY" 142 | } 143 | ], 144 | [ 145 | "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty", 146 | "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty", 147 | { 148 | "aura": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty" 149 | } 150 | ] 151 | ] 152 | }, 153 | "parachainInfo": { 154 | "parachainId": 4435 155 | }, 156 | "polkadotXcm": { 157 | "safeXcmVersion": 4 158 | }, 159 | "sudo": { 160 | "key": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY" 161 | } 162 | } 163 | ``` 164 | 165 | In this example: 166 | 167 | * `balances`: initial account balances 168 | * `collatorSelection`: configure the collatorSelection pallet properties, in this example we set Alice and Bob as initial invulnerable collators. 169 | * `session.keys`: initial session keys 170 | * `parachainInfo.parachainId`: parachain ID 171 | * `sudo.keys`: initial sudo key account 172 | 173 | Note that: 174 | - `5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY`: Alice's account address 175 | - `5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty`: Bob's account address 176 | 177 | ### Generate a customized plain Chainspec 178 | 179 | With the **chain-spec-builder** utility, we can generate a chainspec file using only the runtime wasm file 180 | on which we will apply a patch describing the customized genesis config we want to apply 181 | 182 | Download the chain-spec-builder binary from the latest [polkadot-sdk releases](https://github.com/paritytech/polkadot-sdk/releases/latest). 183 | Then execute it, taking as input the runtime and genesis patch files: 184 | 185 | ```bash 186 | chain-spec-builder -c chainspec.plain.json create -n "Test Parachain" -i test-parachain -t live -r runtime.wasm patch genesis.patch.json 187 | ``` 188 | 189 | To work properly as a parachain chainspec, add the following fields to your `chainspec.plain.json`: 190 | ``` 191 | { 192 | "protocolId": "template-local", 193 | "properties": { 194 | "ss58Format": 42, 195 | "tokenDecimals": 12, 196 | "tokenSymbol": "UNIT" 197 | }, 198 | "para_id": 4435, 199 | "relay_chain": "paseo", 200 | ... 201 | ``` 202 | 203 | You also need to set your `bootNodes` addresses, any node which has a public IP or DNS can be a bootnode: 204 | 205 | ```json 206 | { 207 | "bootNodes": [ 208 | # eg. IP bootnode 209 | "/ip4//tcp/30333/p2p/" 210 | # eg. DNS bootnode 211 | "/dns//tcp/30333/p2p/", 212 | # (Optional) WSS Bootnodes (for light clients, requires a TLS cert, see https://wiki.polkadot.network/docs/maintain-bootnode) 213 | "/dns//tcp/443/wss/p2p/", 214 | ... 215 | } 216 | ``` 217 | 218 | ### Convert your Plain Chainspec to Raw 219 | 220 | To initialize the genesis storage for your chain, you need convert your chainspec from plain to raw format. 221 | This process transforms the human-readable keys in the plain chainspec into actual storage keys and defines a unique genesis block. 222 | 223 | A unique [raw chainspec](https://docs.substrate.io/build/chain-spec/#raw-chain-specifications) can be created from the plain chainspec with this command: 224 | 225 | ``` 226 | parachain-template-node build-spec --chain chainspec.plain.json --raw > chainspec.raw.json 227 | ``` 228 | 229 | ⚠️ Only use the raw chainspec to launch your chain, not the plain chainspec. 230 | 231 | 232 | ### (Optional) Dry-run your Parachain Network Locally 233 | 234 | You should now have everything ready to launch your network locally to validate that everything is properly set up. 235 | 236 | * Start your node (we use the `--tmp` flag to prevent the node database files from being persisted to disk): 237 | 238 | ``` 239 | parachain-template-node --chain chainspec.raw.json --tmp 240 | ```` 241 | * Connect to it with [Polkadot.js Apps](https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A9944) on `ws://127.0.0.1:9944`. 242 | * You can inspect the [chain state in Polkadot.js Apps](https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A9944#/chainstate) to verify that everything is in order for the launch. 243 | 244 | Note: if you look at the node logs, it should be starting to sync the relay-chain (Paseo in our case). For this dry-run step, you don’t have to wait until it is fully synced. However, after deployment, a node needs to be fully synced in order to collate parachain blocks. 245 | 246 | ## Deploy your nodes 247 | 248 | You can use any method you choose to set up your nodes on your machines, we recommend either Ansible or Kubernetes. 249 | 250 | ### Deploy your nodes with Ansible 251 | 252 | Clone the project at [paritytech/parachain-deployment-quickstart](https://github.com/paritytech/parachain-deployment-quickstart/) and follow instructions in the `ansible` folder. 253 | 254 | ### Deploy your nodes with Kubernetes 255 | 256 | Clone the project at [paritytech/parachain-deployment-quickstart](https://github.com/paritytech/parachain-deployment-quickstart/) and follow instructions in the `kubernetes` folder. 257 | 258 | ## Register and activate your Parachain on the Relaychain 259 | 260 | ### Register parachain genesis code and state on relay-chain 261 | 262 | You can export the genesis runtime (WASM code) and state files from your chainspec. Then, these files can be registered on the relaychain to initialize your parachain. 263 | 264 | * Export the genesis state: 265 | ``` 266 | parachain-template-node export-genesis-state --chain chainspec.raw.json > genesis_state_head 267 | ``` 268 | * Export the genesis runtime: 269 | ``` 270 | parachain-template-node export-genesis-wasm --chain chainspec.raw.json > genesis_wasm_code 271 | ``` 272 | * Register your parachain genesis configuration on the relay-chain by executing the `registrar.register` extrinsic on Paseo: 273 | - `id`: your parachain ID 274 | - `genesisHead`: select the `genesis_state_head` file 275 | - `validationCode`: select the `genesis_wasm_code` file 276 | 277 | ### Obtain on-demand coretime to produce your first block 278 | 279 | * Execute extrinsic: `onDemandAssignmentProvider.placeOrderAllowDeath` or `onDemandAssignmentProvider.placeOrderKeepAlive`: 280 | - `maxAmount`: `10000000000000` (13 zeros, ie. 10 ROC) 281 | - `paraId`: your parachain ID 282 | 283 | After executing this, you should have successfully produced your first block ! 284 | 285 | ``` 286 | INFO tokio-runtime-worker substrate: [Parachain] ✨ Imported #1 (0xa075…10d6) 287 | ``` 288 | 289 | ## Manage Coretime for your chain 290 | 291 | To allow your parachain to produce blocks it needs to be allocated [coretime](https://wiki.polkadot.network/docs/learn-agile-coretime) (time allocated for utilizing a core) on the relaychain. 292 | What we mean by "core" is the ability of the relaychain (and its validators) to validate the new blocks of a parachain (received from the collators) so that they are “included” in Polkadot as finalized parachain blocks. 293 | 294 | There are 2 types of coretime: 295 | - **On-demand coretime**: lets users buy coretime by the block. Useful for parachains which don’t require continuous block production 296 | - **Bulk coretime**: an allocation of uninterrupted 28 days (default region length) of coretime (possibly split in timeslices) 297 | 298 | For more information, please refer to the [Parachain Coretime Guide](https://wiki.polkadot.network/docs/learn-guides-coretime-parachains). 299 | 300 | ### Reserve Bulk Coretime 301 | 302 | * Go on [Lastic Rococo Coretime Sales page](https://www.lastic.xyz/rococo/bulkcore1) and buy 1 core 303 | * Go on [Lastic Rococo Homepage](https://www.lastic.xyz/rococo/my-cores), click on the “core nb X” that you own to show its dedicated page, then click "assign core". 304 | Assign it to your ParaID and Finality: `Final` 305 | 306 | Note: any account with enough funds can buy and assign coretime for a parachain. 307 | 308 | ### Renew Bulk Coretime 309 | 310 | TODO 311 | -------------------------------------------------------------------------------- /src/guides/readiness-checklist.md: -------------------------------------------------------------------------------- 1 | # Parachain Production Readiness Checklist 2 | 3 | Before launching your parachain network, verify the readiness of your network infrastructure by reviewing the following five key points. 4 | 5 | 6 | 7 | * [1. Launch your parachain on a testnet before launching on mainnet](#1-launch-your-parachain-on-a-testnet-before-launching-on-mainnet) 8 | * [2. Use Infrastructure as Code](#2-use-infrastructure-as-code) 9 | * [3. Ensure redundancy for your network nodes](#3-ensure-redundancy-for-your-network-nodes) 10 | * [4. Check that your nodes are properly configured to fulfil their roles](#4-check-that-your-nodes-are-properly-configured-to-fulfil-their-roles) 11 | + [Chainspec checks](#chainspec-checks) 12 | + [Bootnode checks](#bootnode-checks) 13 | + [Collator checks](#collator-checks) 14 | + [RPC checks](#rpc-checks) 15 | * [5. Validate that your nodes are fully synced](#5-validate-that-your-nodes-are-fully-synced) 16 | * [6. Set up monitoring and alerting](#6-set-up-monitoring-and-alerting) 17 | - [Tips:](#tips) 18 | 19 | 20 | 21 | ## 1. Launch your parachain on a testnet before launching on mainnet 22 | 23 | The best way to validate your deployment is to deploy a testnet for your parachain. 24 | The recommended relay-chain testnet for builders is now [Paseo](https://github.com/paseo-network) where you can benefit from a stable and mainnet-like experience before onboarding to Polkadot. 25 | 26 | ## 2. Set up your nodes using Infrastructure as Code 27 | 28 | Using Infrastructure as Code for your blockchain nodes helps with the following: 29 | 30 | - **Consistency and Reproducibility**: Reduces manual configurations and allows configuration reuse across testnet and mainnet. 31 | - **Automation and Efficiency**: Although it takes upfront work to set up, you will speed up further deployments by reducing the number of manual steps. 32 | - **Disaster Recovery**: In the event of a disaster, you will be able to quickly restore your infrastructure. 33 | 34 | ## 3. Ensure redundancy for your network nodes 35 | 36 | For a reliable network, it is recommended to have at least: 37 | - 2 Bootnodes 38 | - 2 Collators 39 | - 2 RPC nodes behind a load balancer 40 | 41 | This will help ensure the smooth operation of the network, allowing one node to restart or upgrade while the other still performs its function. 42 | After launch, it is a good idea to increase the size of the network further and decentralize node operations to multiple individuals and organizations. 43 | 44 | ## 4. Check that your nodes are properly configured to fulfil their roles 45 | 46 | ### Chainspec checks 47 | 48 | Your chainspec must: 49 | - Have all the required properties such as `para_id` and `relay_chain` 50 | - Be [converted to raw format](./parachain_deployment.md#convert-your-plain-chainspec-to-raw) 51 | - Have the desired chain state in [its genesis block viewable in a local parachain dry-run](./parachain_deployment.md#optional-dry-run-your-parachain-network-locally) 52 | - Reference your bootnodes addresses so your nodes will connect to the correct network on startup 53 | 54 | ### Bootnode checks 55 | 56 | Your bootnodes must have a fixed network ID and fixed IP or DNS in their addresses, e.g., /dns/polkadot-bootnode-0.polkadot.io/tcp/30333/p2p/12D3KooWSz8r2WyCdsfWHgPyvD8GKQdJ1UAiRmrcrs8sQB3fe2KU. 57 | This can be achieved with these flags, e.g: 58 | 59 | ``` 60 | --node-key-file --listen-addr=/ip4/0.0.0.0/tcp/30333 --listen-addr /ip6/::/tcp/30333 --public-addr=/ip4/PUBLIC_IP/tcp/30333. 61 | ``` 62 | 63 | ⚠️ Your bootnodes should always keep the same addresses across restarts. 64 | 65 | ### Collator checks 66 | 67 | - Each of your collators must have an aura key in their keystore, as explained in the [collator guide](TODO link to collator guide) 68 | - The aura keys also need to be set on-chain, either: 69 | * in the [genesis state directly in the chainspec file](./parachain_deployment.html#prepare-your-genesis-patch-config) 70 | * by [submitting a setKeys extrinsic with your collator account](TODO link to collator guide) 71 | 72 | ### RPC checks 73 | 74 | Your RPC nodes should have those flags enabled: 75 | - `--rpc-external` or `--unsafe-rpc-external` (does the same but doesn't output a warn log) 76 | - `--rpc-methods Safe` 77 | - `--rpc-cors *` 78 | - `--pruning=archive`, you generally want to have your RPC nodes to be archives to access historical blocks. 79 | 80 | You can also add RPC protections flags, e.g.: 81 | 82 | - `--rpc-max-connections 1000`: Allow a maximum of 1000 simultaneous open connection 83 | - `--rpc-rate-limit=10`: Limit to 10 calls per minute 84 | - `--rpc-rate-limit-whitelisted-ips 10.0.0.0/8 1.2.3.4/32`: Disable RPC rate limiting for certain ip addresses 85 | - `--rpc-rate-limit-trust-proxy-headers`: Trust proxy headers for determining the IP for rate limiting 86 | 87 | ## 5. Validate that your nodes are fully synced 88 | 89 | Your parachain nodes should be fully synced with the latest blocks of both your parachain and the relay-chain it is connected to. 90 | 91 | ## 6. Set up monitoring and alerting 92 | 93 | At a minimum, it is recommended to collect your nodes logs and be notified whenever an error or panic logs happens. 94 | 95 | It is highly recommended to set up metrics based monitoring and alerting, including: 96 | - General system-level metrics, e.g. by using the [prometheus node exporter](https://awesome-prometheus-alerts.grep.to/rules.html#host-and-hardware) to watch over disk, cpu, memory, oom kills, etc. 97 | - [Polkadot-sdk native metrics](../monitoring/infrastructure.md#metrics) 98 | 99 | # Tips: 100 | 101 | * For troubleshooting testnets collators you can set`--log parachain=debug`. 102 | Other useful debug targets are`runtime=debug`, `sync=debug`, `author=debug`, `xcm=debug`, etc. 103 | * You should avoid setting trace logging on all your nodes; if you do, set it on a limited number of nodes where it is useful and remove it when not needed anymore. -------------------------------------------------------------------------------- /src/guides/rpc_index.md: -------------------------------------------------------------------------------- 1 | # RPC Overview 2 | 3 | An RPC node is a server that allows external applications to interact with the Polkadot chain. This interaction is facilitated through a set of standardized APIs which enable the execution of various operations and retrieval of blockchain data. Here are some key points about an RPC node in Polkadot: 4 | 5 | Functions of an RPC Node: 6 | *Querying Blockchain Data*: RPC nodes can be used to fetch information from the blockchain, such as block details, transaction histories, account balances, and other state information. 7 | *Submitting Transactions*: External applications can use RPC nodes to broadcast transactions to the network. This includes sending tokens, executing smart contracts, or any other transaction type supported by Polkadot. 8 | *Subscription to Events*: RPC nodes can provide real-time updates on blockchain events, such as new blocks being added, changes in account balances, or other relevant blockchain events. 9 | *Chain State and Metadata*: RPC nodes allow applications to query the current state of the blockchain, as well as metadata about the runtime environment, including the version of the Polkadot runtime, the list of available RPC methods, and more. 10 | 11 | ### Type of RPC Nodes 12 | 13 | There are two common types of RPC nodes: *archive* nodes and *pruned* nodes, which differ in data storage and access. 14 | 15 | - **Archive Nodes**: 16 | - Store the entire blockchain history, providing full state access for tasks requiring historical data, such as analytics and audits. 17 | - Require substantial disk space. 18 | - **Important Flag**: `--state-pruning archive --blocks-pruning archive` (Ensures the node retains all historical data) 19 | 20 | - **Pruned Nodes**: 21 | - Retain only recent data, offering limited historical access but using significantly less storage. 22 | - Suitable for most day-to-day operations and network security. 23 | - **Important Flag**: `--state-pruning 1000` (Only keeps last 1000 of finalized blocks) 24 | 25 | 26 | While archive nodes are essential for applications needing comprehensive historical data, pruned nodes are sufficient for wallets, validators, and other typical uses. 27 | 28 | 29 | ### Important Flags for Running an RPC Node 30 | 31 | 1. **`--rpc-methods`**: Defines which RPC methods are available. 32 | - Example: `--rpc-methods=Unsafe` 33 | - Options: `Auto`, `Safe`, `Unsafe` 34 | 35 | 2. **`--rpc-cors`**: Specifies the Cross-Origin Resource Sharing (CORS) settings. 36 | - Example: `--rpc-cors=all` (Allow all origins) 37 | - Example: `--rpc-cors=http://localhost:3000` (Allow specific origin) 38 | 39 | 3. **`--rpc-port`**: Sets the port on which the RPC server listens. 40 | - Example: `--rpc-port=9933` 41 | 42 | 4. **`--rpc-external`**: Allows RPC connections from external sources. 43 | - Example: `--rpc-external` 44 | 45 | 5. **`--rpc-rate-limit`**: RPC rate limiting (calls/minute) for each connection.. 46 | - Example: `--rpc-rate-limit=100` 47 | 48 | 6. **`--unsafe-rpc-external`**: Same as `--rpc-external` 49 | - Example: `--unsafe-rpc-external` 50 | 51 | 52 | ### Securing the WS Port 53 | 54 | Securing the WebSocket (WS) port is essential to prevent unauthorized access and potential security threats such as data breaches, man-in-the-middle attacks, and denial-of-service attacks. It is also necessary to access the node from the Polkadot-js UI. 55 | 56 | #### Tools for Securing WebSocket Connections 57 | 58 | A list of most common tools available that supports securing websocket: 59 | 60 | 1. **NGINX**: A popular web server and reverse proxy that can be configured to handle WebSocket connections securely. 61 | - **Documentation**: [NGINX WebSocket Support](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/) 62 | 63 | 2. **HAProxy**: A high-performance TCP/HTTP load balancer that can manage WebSocket connections securely. 64 | - **Documentation**: [HAProxy WebSocket Support](http://www.haproxy.org/#docs) 65 | 66 | 3. **Traefik**: A modern reverse proxy and load balancer that supports WebSocket connections and integrates well with various security features. 67 | - **Documentation**: [Traefik WebSocket Support](https://doc.traefik.io/traefik/routing/overview/) 68 | 69 | 4. **Cloudflare**: Provides WebSocket support along with security features like DDoS protection and WAF. 70 | - **Documentation**: [Cloudflare WebSocket Support](https://developers.cloudflare.com/network/websockets/) 71 | 72 | 5. **AWS Application Load Balancer (ALB)**: Supports WebSocket connections and integrates with AWS WAF for additional security. 73 | - **Documentation**: [AWS ALB WebSocket Support](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) 74 | 75 | 6. **Caddy**: A web server with automatic HTTPS that can also handle WebSocket connections securely. 76 | - **Documentation**: [Caddy WebSocket Support](https://caddyserver.com/docs/v2-upgrade#proxy) 77 | 78 | ### How-to Guides 79 | 80 | This section provides a deployment guide for an RPC node via Ansible and Kubernetes. 81 | -------------------------------------------------------------------------------- /src/guides/rpc_kubernetes.md: -------------------------------------------------------------------------------- 1 | # Guide: Deploying an RPC node 2 | 3 | This guide demonstrates the deployment of an RPC node via Helm chart in Kubernetes. 4 | 5 | 6 | ## Preparations 7 | 8 | Parity maintains a helm GitHub repo @ [https://github.com/paritytech/helm-charts](https://github.com/paritytech/helm-charts) - Inside this repo is the [node](https://github.com/paritytech/helm-charts/tree/main/charts/node) chart which can be used for deploying your Substrate/Polkadot binary. 9 | 10 | All variables are documented clearly in the [README.md](https://github.com/paritytech/helm-charts/blob/main/charts/node/README.md) and there’s an example [local-rococo](https://github.com/paritytech/helm-charts/tree/main/charts/node/examples/local-rococo) which you can start working from. 11 | 12 | 13 | #### Helm Deployment 14 | 15 | 16 | Binary images are available at Dockerhub. Parity maintains both [Polkadot](https://hub.docker.com/r/parity/polkadot) and [Polkadot-Parachain](https://hub.docker.com/r/parity/polkadot-parachain) images from the [polkadot-sdk](https://github.com/paritytech/polkadot-sdk) repo. 17 | 18 | When running an RPC node, a sidecar called [ws-health-exporter](https://github.com/paritytech/scripts/tree/master/dockerfiles/ws-health-exporter) is good to have to allow a readiness endpoint for Kubernetes. 19 | 20 | 21 | ```bash 22 | helm repo add parity https://paritytech.github.io/helm-charts/ 23 | helm -n NAMESPACE upgrade --install RELEASE_NAME -f FILE_NAME.yml parity/node 24 | ``` 25 | 26 | #### Relaychain Helm Values 27 | 28 | ``` 29 | image: 30 | repository: parity/polkadot 31 | tag: v1.14.0 32 | node: 33 | replicas: 1 34 | chain: westend 35 | role: full 36 | chainData: 37 | chainPath: westend2 38 | volumeSize: 600Gi 39 | storageClass: ssd-csi 40 | database: paritydb 41 | pruning: archive 42 | chainKeystore: 43 | mountInMemory: 44 | enabled: true 45 | flags: 46 | - "--rpc-max-connections 5000" 47 | perNodeServices: 48 | relayP2pService: 49 | enabled: true 50 | type: NodePort 51 | setPublicAddressToExternalIp: 52 | enabled: true 53 | persistGeneratedNodeKey: true 54 | enableOffchainIndexing: true 55 | serviceMonitor: 56 | enabled: true 57 | tracing: 58 | enabled: false 59 | resources: 60 | requests: 61 | cpu: 500m 62 | memory: 2Gi 63 | limits: 64 | cpu: 4 65 | memory: 7Gi 66 | 67 | # RPC Endpoint 68 | ingress: 69 | enabled: false 70 | annotations: 71 | kubernetes.io/ingress.class: TODO 72 | external-dns.alpha.kubernetes.io/target: TODO 73 | cert-manager.io/cluster-issuer: TODO 74 | host: parachain.example.com 75 | tls: 76 | - secretName: parachain.example.com 77 | hosts: 78 | - parachain.example.com 79 | 80 | extraContainers: 81 | - name: ws-health-exporter 82 | image: docker.io/paritytech/ws-health-exporter:0a2e6e9b-20230412 83 | env: 84 | - name: WSHE_NODE_RPC_URLS 85 | value: "ws://127.0.0.1:9944" 86 | - name: WSHE_NODE_MAX_UNSYNCHRONIZED_BLOCK_DRIFT 87 | value: "4" 88 | - name: WSHE_NODE_MIN_PEERS 89 | value: "2" 90 | resources: 91 | requests: 92 | cpu: 10m 93 | memory: 32M 94 | limits: 95 | cpu: 100m 96 | memory: 64M 97 | readinessProbe: 98 | httpGet: 99 | path: /health/readiness 100 | port: 8001 101 | ``` 102 | 103 | #### Parachains Helm Values 104 | 105 | ``` 106 | image: 107 | repository: parity/polkadot-parachain 108 | tag: 1.14.0 109 | node: 110 | chain: bridge-hub-westend 111 | command: polkadot-parachain 112 | replicas: 1 113 | role: full 114 | chainData: 115 | database: paritydb 116 | pruning: archive 117 | volumeSize: 50Gi 118 | storageClass: ssd-csi 119 | chainKeystore: 120 | mountInMemory: 121 | enabled: true 122 | isParachain: true 123 | collatorRelayChain: 124 | chain: westend 125 | chainData: 126 | database: paritydb 127 | pruning: 1000 128 | storageClass: ssd-csi 129 | volumeSize: 150Gi 130 | chainPath: westend2 131 | chainKeystore: 132 | mountInMemory: 133 | enabled: true 134 | flags: 135 | - "--rpc-max-connections 1000" 136 | perNodeServices: 137 | relayP2pService: 138 | enabled: true 139 | type: NodePort 140 | paraP2pService: 141 | enabled: true 142 | type: NodePort 143 | setPublicAddressToExternalIp: 144 | enabled: true 145 | resources: 146 | requests: 147 | cpu: 1 148 | memory: 2Gi 149 | limits: 150 | memory: 4Gi 151 | 152 | # RPC Endpoint 153 | ingress: 154 | enabled: false 155 | annotations: 156 | kubernetes.io/ingress.class: TODO 157 | external-dns.alpha.kubernetes.io/target: TODO 158 | cert-manager.io/cluster-issuer: TODO 159 | host: parachain.example.com 160 | tls: 161 | - secretName: parachain.example.com 162 | hosts: 163 | - parachain.example.com 164 | ``` 165 | 166 | ### Best Practices 167 | 168 | * The advantage of running in Kubernetes is the number of replicas can easily be added behind an ingress. 169 | * A backup is ideally used due to easily scale up new RPC nodes 170 | * Enabling serviceMonitor to enable monitoring of the RPC nodes -------------------------------------------------------------------------------- /src/guides/subkey.md: -------------------------------------------------------------------------------- 1 | # Subkey 2 | `subkey` is a cli tool for generating substrate based account. It can also be used for signing and verifying messages, but in this doc we only cover account creation and node key (libp2p) generation. 3 | 4 | # Installation 5 | In order to install the tool, please reference the substrate documentation: https://docs.substrate.io/reference/command-line-tools/subkey/#installation 6 | 7 | # Generate Substrate Based Accounts 8 | As mentioned earlier, subkey can be used to generate accounts for different substrate chains and parachains, including polkadot, kosama, moonbeam, etc. 9 | 10 | By default, `substrate generate` command generate an account for substrate network. By adding `--network `, one could generate accounts for other networks. 11 | 12 | ``` 13 | > subkey generate 14 | Secret phrase: claim year obvious artist also float royal vague industry tackle husband prize 15 | Network ID: substrate 16 | Secret seed: 0x4548be7dc2fa89b3e5600f3933d69ffac4d06e0ac6222ccb9a17fe3cb49ebd9d 17 | Public key (hex): 0x10938f06b4265ac2bef65bc5d3e3d8ce20b12bc07d2d45ca1463ba2f1a47a078 18 | Account ID: 0x10938f06b4265ac2bef65bc5d3e3d8ce20b12bc07d2d45ca1463ba2f1a47a078 19 | Public key (SS58): 5CSSTUxjWVAWSLDxigjsyAF2PXLCznf1FSUhbDooTwaaWQM1 20 | SS58 Address: 5CSSTUxjWVAWSLDxigjsyAF2PXLCznf1FSUhbDooTwaaWQM1 21 | 22 | > substrate generate --network polkadot 23 | Secret phrase: spell subject sleep celery cigar term neck tube blossom inflict session baby 24 | Network ID: polkadot 25 | Secret seed: 0x50893f76f50855f9ca891dfa55ef64f51ad744f3d643f3f8046ef13b6b249baa 26 | Public key (hex): 0x847ace070b6bb193659379f1c64e8f3dda721ba545bfaee6fbb717df84ef247f 27 | Account ID: 0x847ace070b6bb193659379f1c64e8f3dda721ba545bfaee6fbb717df84ef247f 28 | Public key (SS58): 13zhoUzf3rqj5uzgFAuquf7DrgofKrUHBjUemarXS78G4Bon 29 | SS58 Address: 13zhoUzf3rqj5uzgFAuquf7DrgofKrUHBjUemarXS78G4Bon 30 | ``` 31 | 32 | - The seed phrase must be saved and stored in a safe place to be able to recover your account information (public and private keys). 33 | - The `SS58 Address` is the account address on different network (aka wallet address). 34 | - The `Network ID` field indicate the network name that this account belongs to. 35 | 36 | # Retrieve Accounts From the Seed Phrase 37 | `subkey inspect` subcommand can be used to retrieve the account information from the seed phrase: 38 | 39 | ``` 40 | > subkey inspect "claim year obvious artist also float royal vague industry tackle husband prize" 41 | Secret phrase: claim year obvious artist also float royal vague industry tackle husband prize 42 | Network ID: substrate 43 | Secret seed: 0x4548be7dc2fa89b3e5600f3933d69ffac4d06e0ac6222ccb9a17fe3cb49ebd9d 44 | Public key (hex): 0x10938f06b4265ac2bef65bc5d3e3d8ce20b12bc07d2d45ca1463ba2f1a47a078 45 | Account ID: 0x10938f06b4265ac2bef65bc5d3e3d8ce20b12bc07d2d45ca1463ba2f1a47a078 46 | Public key (SS58): 5CSSTUxjWVAWSLDxigjsyAF2PXLCznf1FSUhbDooTwaaWQM1 47 | SS58 Address: 5CSSTUxjWVAWSLDxigjsyAF2PXLCznf1FSUhbDooTwaaWQM1 48 | 49 | > subkey inspect --network polkadot "spell subject sleep celery cigar term neck tube blossom inflict session baby" 50 | Secret phrase: spell subject sleep celery cigar term neck tube blossom inflict session baby 51 | Network ID: polkadot 52 | Secret seed: 0x50893f76f50855f9ca891dfa55ef64f51ad744f3d643f3f8046ef13b6b249baa 53 | Public key (hex): 0x847ace070b6bb193659379f1c64e8f3dda721ba545bfaee6fbb717df84ef247f 54 | Account ID: 0x847ace070b6bb193659379f1c64e8f3dda721ba545bfaee6fbb717df84ef247f 55 | Public key (SS58): 13zhoUzf3rqj5uzgFAuquf7DrgofKrUHBjUemarXS78G4Bon 56 | SS58 Address: 13zhoUzf3rqj5uzgFAuquf7DrgofKrUHBjUemarXS78G4Bon 57 | ``` 58 | 59 | # Derived Accounts (Child Accounts) 60 | The `subkey` programs supports creation of sub accounts which are derived from the exact same seed phrase, so that there'd be no need for additional seed phrases for new accounts. One use case is when you want to create multiple accounts for different validators/collators, without needing to create and store many seed phrases. 61 | 62 | To derive a child key pair, you add two slashes (//), a derivation path, and an index after the secret phrase associated with its parent key. Because you derive child key pairs and addresses from keys that have been previously generated, you use the subkey inspect command. For example: 63 | 64 | ``` 65 | > subkey inspect "claim year obvious artist also float royal vague industry tackle husband prize//validator-1//beefy" 66 | Network ID: substrate 67 | Secret seed: 0xb60b7b15155936780cd83063e169bc8402276b253a1d75fa678cc547dd530eb2 68 | Public key (hex): 0x269c50d4065b4bf58839df4cfc16a11b367b80fbf00d21a96da863d8659e720a 69 | Account ID: 0x269c50d4065b4bf58839df4cfc16a11b367b80fbf00d21a96da863d8659e720a 70 | Public key (SS58): 5CwL7TsLnqQKakTfweh5aZ27fe9GHySP86YwbHtLUK3p649g 71 | SS58 Address: 5CwL7TsLnqQKakTfweh5aZ27fe9GHySP86YwbHtLUK3p649g 72 | 73 | 74 | > subkey inspect "claim year obvious artist also float royal vague industry tackle husband prize//validator-1//babe" 75 | Network ID: substrate 76 | Secret seed: 0xb31ee2df80a708917b62683579164f625be935a4c3760b24cd3f60f630e0ee2e 77 | Public key (hex): 0x00493534063762b76cb4ffad8336e57af312c02a6155a871600040de6f1d936a 78 | Account ID: 0x00493534063762b76cb4ffad8336e57af312c02a6155a871600040de6f1d936a 79 | Public key (SS58): 5C55c1YcFWQV6XdFCQVpG52K1SjgZqWKDvg7uNe9PFX4Hc9x 80 | SS58 Address: 5C55c1YcFWQV6XdFCQVpG52K1SjgZqWKDvg7uNe9PFX4Hc9x 81 | ``` 82 | 83 | **Important Note:** Both seed phrase and derivation paths need to be stored to be able to arrive at the key for an address. Only use custom derivation paths if you are comfortable with your knowledge of this topic. 84 | 85 | # Generate Node Keys (`libp2p` Keys) 86 | Use the `subkey generate-node-key` command to generate random public and private keys for peer-to-peer (`libp2p`) communication between Substrate nodes. The public key is the peer identifier that is used in chain specification files or as a command-line argument to identify a node participating in the blockchain network. In most cases, you run this command with a command-line option to save the private key to a file. 87 | 88 | To generate a random key pair for peer-to-peer communication and save the secret key in a file, run a command similar to the following: 89 | ``` 90 | > subkey generate-node-key --file ../generated-node-key 91 | 12D3KooWMUsb8yizAaQiFRPtuqJTK9c7CSektH5YFV3MGxHGJbnV 92 | ``` 93 | This command displays the peer identifier for the node key in the terminal and the private key is saved in the generated-node-key file. In this example, the saved key in the parent directory instead of the current working directory. 94 | ``` 95 | 12D3KooWHALHfL7dDBiGTt4JTEAvCbDWts8zHwvcPvJXDF9fxue7 96 | ``` 97 | 98 | Use the `subkey inspect-node-key` command to display the peer identifier for the node that corresponds with the node key in the specified file name. Before using this command, you should have previously used the `subkey generate-node-key` command and saved the key to a file. 99 | ``` 100 | > subkey inspect-node-key --file 101 | ``` 102 | -------------------------------------------------------------------------------- /src/icons/feeds.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/icons/feeds.png -------------------------------------------------------------------------------- /src/icons/figma.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/icons/figma.png -------------------------------------------------------------------------------- /src/icons/github.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/icons/github.png -------------------------------------------------------------------------------- /src/icons/gitlab.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/icons/gitlab.png -------------------------------------------------------------------------------- /src/icons/jira.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/icons/jira.png -------------------------------------------------------------------------------- /src/icons/webhooks.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/icons/webhooks.png -------------------------------------------------------------------------------- /src/images/3osxC7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/images/3osxC7.png -------------------------------------------------------------------------------- /src/images/AEEVr6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/images/AEEVr6.png -------------------------------------------------------------------------------- /src/images/lb0gOx.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/images/lb0gOx.png -------------------------------------------------------------------------------- /src/images/metric_dashboard.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/images/metric_dashboard.png -------------------------------------------------------------------------------- /src/images/rococo-collators-1002.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/images/rococo-collators-1002.png -------------------------------------------------------------------------------- /src/images/rococo-parachains.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/images/rococo-parachains.png -------------------------------------------------------------------------------- /src/images/rococo-validator-a-node-0.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/images/rococo-validator-a-node-0.png -------------------------------------------------------------------------------- /src/images/testnet-mgr-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/images/testnet-mgr-api.png -------------------------------------------------------------------------------- /src/images/testnet-mgr.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/paritytech/devops-guide/a566801793c4cca0bda128b32c0071923f6c8ec5/src/images/testnet-mgr.png -------------------------------------------------------------------------------- /src/kubernetes/helm.md: -------------------------------------------------------------------------------- 1 | # Helm Chart 2 | 3 | ## Overview 4 | 5 | Parity maintains a helm GitHub repo @ [https://github.com/paritytech/helm-charts](https://github.com/paritytech/helm-charts) - Inside this repo is the [node](https://github.com/paritytech/helm-charts/tree/main/charts/node) chart which should be used for deploying your Substrate/Polkadot binary. 6 | 7 | All variables are documented clearly in the [README.md](https://github.com/paritytech/helm-charts/blob/main/charts/node/README.md) and there’s an example [local-rococo](https://github.com/paritytech/helm-charts/tree/main/charts/node/examples/local-rococo) which you can start working from. 8 | 9 | ### Example Rococo Local Chain 10 | 11 | This is a simple example of deploying a `rococo-local` test chain in Kubernetes. Two validators and two full nodes will be deployed via the helm chart. Once both validators are running you will see block production. A custom node key is used on the `Alice` validator which all other hosts use as a bootnode. 12 | 13 | #### First install the helm repo 14 | 15 | ```bash 16 | helm repo add parity https://paritytech.github.io/helm-charts/ 17 | ``` 18 | 19 | #### Deploy Validator Alice 20 | 21 | Alice will be deployed in a stateful set and use an example custom node key, along with deploying a service to be used as a bootnode: 22 | 23 | ```bash 24 | helm install rococo-alice parity/node --set node.role="validator" --set node.customNodeKey="91cb59d86820419075b08e3043cd802ba3506388d8b161d2d4acd203af5194c1" --set node.chain=rococo-local --set node.perNodeServices.relayP2pService.enabled=true --set node.perNodeServices.relayP2pService.port=30333 --set node.flags="--alice --rpc-external --ws-external --rpc-cors all --rpc-methods=unsafe" 25 | ``` 26 | 27 | #### Deploy Validator Bob 28 | 29 | ```bash 30 | helm install rococo-bob parity/node --set node.role="validator" --set node.chain=rococo-local --set node.flags="--bob --bootnodes '/dns4/rococo-alice-node-0-relay-chain-p2p/tcp/30333/p2p/12D3KooWMeR4iQLRBNq87ViDf9W7f6cc9ydAPJgmq48rAH116WoC'" 31 | ``` 32 | 33 | #### Deploy Two Full Nodes 34 | 35 | ```bash 36 | helm install rococo-pool parity/node --set node.chain=rococo-local --set node.replicas=2 --set node.flags="--bootnodes '/dns4/rococo-alice-node-0-relay-chain-p2p/tcp/30333/p2p/12D3KooWMeR4iQLRBNq87ViDf9W7f6cc9ydAPJgmq48rAH116WoC'" 37 | ``` 38 | 39 | Once these steps are complete you will have a working `rococo-local` test chain with two validators and two full nodes. 40 | 41 | #### GitOps Tooling 42 | 43 | Below are some useful GitOps tool for managing helm releases. Here is a list of tool from simplest to more advanced: 44 | 45 | - [Helmfile](https://github.com/roboll/helmfile) 46 | - [Terraform Helm provider](https://registry.terraform.io/providers/hashicorp/helm/latest/docs) 47 | - [Flux CD](https://fluxcd.io/) 48 | - [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) 49 | 50 | ## Important Chart Options 51 | 52 | | Option | Description | 53 | | ----------------------- | ------------------------------------- | 54 | | node.chain | Network to connect to | 55 | | node.command | Binary to use | 56 | | node.flags | Flags to use with binary in container | 57 | | node.customChainspecUrl | Custom Chainspec URL | 58 | -------------------------------------------------------------------------------- /src/kubernetes/index.md: -------------------------------------------------------------------------------- 1 | # Kubernetes 2 | 3 | As previously mentioned, Kubernetes deployments are only recommended for people with good prior operating experience of Kubernetes. 4 | -------------------------------------------------------------------------------- /src/kubernetes/key_injection_test.md: -------------------------------------------------------------------------------- 1 | # Polkadot Key Injection 2 | 3 | ## Chart Settings: 4 | 5 | Ensure `allowUnsafeRpcMethods: true` is set in the helm chart values. 6 | 7 | ## Example Key Injection Values: 8 | 9 | Add example keys, in this case ``//Testing/babe`` (sr25519) and ``//Testing//gran`` (ed25519) on chain `polkadot-dev`: 10 | 11 | ``` 12 | keys: 13 | - type: "gran" 14 | scheme: "ed25519" 15 | seed: "//Testing//gran" 16 | - type: "babe" 17 | scheme: "sr25519" 18 | seed: "//Testing" 19 | extraDerivation: //babe 20 | ``` 21 | 22 | ## Get public keys: 23 | 24 | ``` 25 | $ polkadot key inspect //Testing//babe --network polkadot 26 | Secret Key URI `//Testing//babe` is account: 27 | Network ID: polkadot 28 | Secret seed: 0x35993b5ca38b5909a26dbc15b736dede3bdf233ce63380f6ae62cb0ca096483b 29 | Public key (hex): 0x28c63dd7bb87238daf363a539da87d3c67d66a199e24f7751432e4f2363e8147 30 | Account ID: 0x28c63dd7bb87238daf363a539da87d3c67d66a199e24f7751432e4f2363e8147 31 | Public key (SS58): 1vToiVGY8q2kuG5XaN4JXrydgmkvoNMPpbwb9fPU8uQuRM5 32 | SS58 Address: 1vToiVGY8q2kuG5XaN4JXrydgmkvoNMPpbwb9fPU8uQuRM5 33 | ``` 34 | 35 | ``` 36 | $ polkadot key inspect //Testing//gran --network polkadot --scheme ed25519 37 | Secret Key URI `//Testing//gran` is account: 38 | Network ID: polkadot 39 | Secret seed: 0xbfc22ae1e901dbd25057747b315481cf8a470261ea81892a9aa31be1391a0dcb 40 | Public key (hex): 0x7819b7ddc959b749a5da604c3a2d7d3e0097760be603d596f19d116d6207ad38 41 | Account ID: 0x7819b7ddc959b749a5da604c3a2d7d3e0097760be603d596f19d116d6207ad38 42 | Public key (SS58): 13iUPPkgWezjEpxFyfCKczLkrsBtJfwMWYhjDRwvtCKp1v3s 43 | SS58 Address: 13iUPPkgWezjEpxFyfCKczLkrsBtJfwMWYhjDRwvtCKp1v3s 44 | ``` 45 | 46 | - Babe key: 0x28c63dd7bb87238daf363a539da87d3c67d66a199e24f7751432e4f2363e8147 47 | - Grandpa Key: 0x7819b7ddc959b749a5da604c3a2d7d3e0097760be603d596f19d116d6207ad38 48 | 49 | ## Verify keys exist 50 | 51 | ``` 52 | $ yarn run:api rpc.author.hasKey 0x28c63dd7bb87238daf363a539da87d3c67d66a199e24f7751432e4f2363e8147 babe 53 | { 54 | "hasKey": true 55 | } 56 | ``` 57 | 58 | ``` 59 | $ yarn run:api rpc.author.hasKey 0x7819b7ddc959b749a5da604c3a2d7d3e0097760be603d596f19d116d6207ad38 gran 60 | { 61 | "hasKey": true 62 | } 63 | ``` 64 | 65 | -------------------------------------------------------------------------------- /src/kubernetes/testnetmanager.md: -------------------------------------------------------------------------------- 1 | # Testnet Manager 2 | 3 | The [Testnet manager](https://github.com/paritytech/testnet-manager) ([helm chart](https://github.com/paritytech/helm-charts/tree/main/charts/testnet-manager)) lets you dynamically control test networks via a simple UI or API. It gives you a single pane of glass to list, inspect and interact with the nodes (full nodes, validators and parachain collators) running in a given Kubernetes namespace. 4 | 5 | ## Rococo Example View 6 | 7 | ### List Parachains 8 | 9 | ![rococo-parachains](../images/rococo-parachains.png) 10 | 11 | ### List Parachain Collators 12 | 13 | ![rococo-collators-1002](../images/rococo-collators-1002.png) 14 | 15 | ### Inspect Validator Node 16 | 17 | ![rococo-validator-a-node-0](../images/rococo-validator-a-node-0.png) 18 | 19 | ## Usage 20 | 21 | ### Requirements 22 | 23 | The testnet manager requires the chain Sudo seed phrase to perform management functions. Also, some chain specific variables should be defined in a configmap, this can be added to the `values.yaml`: 24 | 25 | ```yaml 26 | configmap: 27 | WS_ENDPOINT: "ws://rococo-alice-node-0.rococo:9944" 28 | NODE_HTTP_PATTERN: "http://NODE_NAME.rococo:9933" 29 | NODE_WS_PATTERN: "ws://NODE_NAME.rococo:9944" 30 | HEALTHY_MIN_PEER_COUNT: "1" 31 | LOG_LEVEL: DEBUG 32 | 33 | secret: 34 | SUDO_SEED: "0xe5be9a5092b81bca64be81d212e7f2f9eba183bb7a90954f7b76361f6edb5c0a" # Alice 35 | VALIDATORS_ROOT_SEED: "test test test test test test test test test test test test" 36 | ``` 37 | 38 | Then install the testnet manager and port forward a connection using the output of `helm install ...`: 39 | 40 | ```bash 41 | helm repo add parity https://paritytech.github.io/helm-charts/ 42 | helm repo update 43 | helm install testnet-mgr parity/testnet-manager --values values.yaml 44 | ``` 45 | 46 | ### Frontend GUI 47 | 48 | In the nodes section you can view all running nodes, their roles, chain, uptime, CLI arguments, and you can also view logs. 49 | 50 | ![testnet-mgr-frontend](../images/testnet-mgr.png) 51 | 52 | ### Interact with API via Frontend 53 | 54 | It's possible to view the API calls and execute them via the GUI. The main functions are: 55 | 56 | - Viewing nodes, validators, collators and parachains 57 | - Registering / deregistering validators and collators 58 | - Onboarding / off-boarding parachains 59 | - Rotating session keys 60 | 61 | ![testnet-mgr-api](../images/testnet-mgr-api.png) 62 | 63 | ### Examples 64 | 65 | Register a new validator in the `StatefulSet` called `rococo-val-pool`: 66 | 67 | ```bash 68 | curl -X 'POST' \ 69 | 'http://localhost:8080/api/register_validators?statefulset=rococo-val-pool' \ 70 | -H 'accept: application/json' \ 71 | -d '' 72 | ``` 73 | 74 | Onboard Parachain id 1000: 75 | 76 | ```bash 77 | curl -X 'POST' \ 78 | 'http://localhost:8080/api/onboard_parachain/1000' \ 79 | -H 'accept: application/json' \ 80 | -d '' 81 | ``` 82 | 83 | ### How does it work ? 84 | 85 | The testnet-manager is deployed in the same Kubernetes namespaces as nodes deployed with the [node helm-chart](https://github.com/paritytech/helm-charts/tree/main/charts/node). As node pods deployed with the chart are tagged with the appropriate labels (e.g. chain name, para ID), the manager is able to query the Kubernetes API and list the running nodes for each network (relay-chain, parachains). 86 | 87 | By combining this list of nodes with the on-chain state retrieved from RPC endpoints (e.g. list of active validators accounts), the manager can automate node key setup (by interacting directly with each node RPC endpoint) and registration (by submitting sudo extrinsics). Behind the scenes, it uses a derivation formula for generating deterministic Validator/Collator accounts addresses: "${VALIDATORS_ROOT_SEED}//${node-name}". 88 | -------------------------------------------------------------------------------- /src/monitoring/index.md: -------------------------------------------------------------------------------- 1 | # Monitoring Overview 2 | 3 | Monitoring can be categorized into two main areas: 4 | 5 | ### On-chain 6 | This involves tracking events that occur on the blockchain. Examples include: 7 | - Transactions by specific addresses 8 | - Changes in the validator set 9 | 10 | On-chain monitoring typically involves checking blockchain data via RPC nodes to assess values, delays, and the timing of events. It is recommended to run your own RPC servers to avoid potential issues with public RPC nodes. There are useful tools such as [Polkabot](https://gitlab.com/Polkabot/polkabot) and [Polkadot-Basic-Notification](https://github.com/paritytech/polkadot-basic-notification) to help with on-chain monitoring. 11 | 12 | 13 | ### On-Host 14 | 15 | On-host monitoring involves tracking the individual node itself. Examples include: 16 | - Current block height 17 | - Number of peer-to-peer (P2P) connections 18 | - Finality lag 19 | 20 | To monitor individual node, polkadot-sdk binary exposes metrics in a Prometheus type format at . By default, this endpoint is only exposed on the local network interface, but you can expose it on all interfaces using the `--prometheus-external` flag. 21 | 22 | As the metrics provided by these endpoints don't include hosts metrics (e.g. CPU, memory, bandwidth usage), it is recommended to complement it with other tools such as [Prometheus node exporter](https://github.com/prometheus/node_exporter) which needs to be installed on the same host. 23 | 24 | 25 | # Monitoring Stack 26 | 27 | ### Polkadot tools 28 | 29 | - [polkadot-introspector](https://github.com/paritytech/polkadot-introspector): The Polkadot Introspector is a collection of tools for monitoring and introspection of Polkadot or other substrate-based blockchains. 30 | - [polkadot-telemetry](https://github.com/paritytech/substrate-telemetry): The telemetry server is used for real time information from nodes, showing information about their name, location, current best & finalized blocks, and others. It gives a useful dashboard to view the state of nodes. An example of live running Telemetry site is https://telemetry.polkadot.io/ 31 | 32 | 33 | ### Non-Polkadot specific tools 34 | The recommended Polkadot monitoring stack consists of the following tools: 35 | 36 | - [Prometheus](./prometheus.md): A systems and service monitoring system based on a timeseries database. 37 | - [Grafana](./grafana.md): allows you to query, visualize, and understand your metrics. 38 | - [Alertmanager](./alertmanager.md): Creates and routes alerts to the tool of your choice (Email / SMS / Telegram / PagerDuty / Slack / Matrix) based on alert rules and metrics 39 | - [Loki](./loki.md) - A highly scalable log aggregation system that allows you to view and search logs from all your infrastructure in one place. 40 | 41 | For available set of Polkadot dashboards, alerts and rules are listed in [polkadot-monitoring-mixin](https://github.com/paritytech/polkadot-monitoring-mixin) repository. 42 | 43 | An example of the metric dashboard from polkadot-monitoring-mixin: 44 | 45 | ![metric_dashboard](../images/metric_dashboard.png) -------------------------------------------------------------------------------- /src/monitoring/infrastructure.md: -------------------------------------------------------------------------------- 1 | ## Infrastructure Tools 2 | 3 | Prometheus, Loki, Alertmanager, and Grafana are powerful tools commonly used for monitoring and visualizing metrics and logs in a distributed system. Here, we focus on integrating these tools to effectively monitor Polkadot metrics across relay chains and parachains. 4 | 5 | ### Metrics 6 | 7 | [Prometheus](https://prometheus.io/docs/introduction/overview/) is an open source solution that can be used to collect metrics from applications. 8 | It collects metrics from configured targets endpoints at given intervals, evaluates rule expressions, displays the results, and can trigger alerts when specified conditions are observed. 9 | 10 | #### Prometheus Configuration 11 | 12 | Targets are a list of endpoints you want to scrape. The two main exporters we care about are for 1) polkadot/substrate and 2) the node-exporter. An example of scraping these on the IP address 10.100.0.0 would be: 13 | 14 | ```yaml 15 | scrape_configs: 16 | - job_name: polkadot 17 | static_configs: 18 | - targets: 19 | - 10.100.0.0:9080 # promtail 20 | - 10.100.0.0:9100 # node exporter 21 | - 10.100.0.0:9615 # relaychain metrics 22 | - 10.100.0.0:9625 # parachain metrics 23 | ``` 24 | 25 | ### Logs 26 | 27 | [Loki](https://grafana.com/docs/loki/latest/) is an open source solution that can be used to aggregate logs from applications, allowing the operator to see errors, patterns and be able to search through the logs from all hosts very easily. An agent such as [Promtail](https://grafana.com/docs/loki/latest/send-data/promtail) or [Grafana Alloy]() is used to push logs to the Loki server. 28 | 29 | Example promtail.yaml configuration to collect the logs and create a Promtail metrics that aggregates each log level: 30 | 31 | ```yaml 32 | # promtail server config 33 | server: 34 | http_listen_port: 9080 35 | grpc_listen_port: 0 36 | log_level: info 37 | positions: 38 | filename: /var/lib/promtail/positions.yaml 39 | 40 | # loki servers 41 | clients: 42 | - url: http://loki.example.com/loki/api/v1/push 43 | backoff_config: 44 | min_period: 1m 45 | max_period: 1h 46 | max_retries: 10000 47 | 48 | scrape_configs: 49 | - job_name: journald 50 | journal: 51 | max_age: 1m 52 | path: /var/log/journal 53 | labels: 54 | job: journald 55 | pipeline_stages: 56 | - match: 57 | selector: '{job="journald"}' 58 | stages: 59 | - multiline: 60 | firstline: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}' 61 | max_lines: 2500 62 | - regex: 63 | expression: '(?P\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3})\s+(?P(TRACE|DEBUG|INFO|WARN|ERROR))\s+(?P([^\s]+))\s+(?P[\w-]+):?:?(?P[\w-]+)?:[\s]?(?P\[[\w-]+\]+)?[\s]?(?P.+)' 64 | - labels: 65 | level: 66 | target: 67 | subtarget: 68 | - metrics: 69 | log_lines_total: 70 | type: Counter 71 | Description: "Total Number of Chain Logs" 72 | prefix: "promtail_chain_" 73 | max_idle_duration: 24h 74 | config: 75 | match_all: true 76 | action: inc 77 | - match: 78 | selector: '{job="journald", level="ERROR"}' 79 | stages: 80 | - multiline: 81 | firstline: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}' 82 | max_lines: 2500 83 | - metrics: 84 | log_lines_total: 85 | type: Counter 86 | Description: "Total Number of Chain Error Logs" 87 | prefix: "promtail_chain_error_" 88 | max_idle_duration: 24h 89 | config: 90 | match_all: true 91 | action: inc 92 | - match: 93 | selector: '{job="journald", level=~".+"} |~ "(?i)(panic)"' 94 | stages: 95 | - multiline: 96 | firstline: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}' 97 | max_lines: 2500 98 | - metrics: 99 | log_lines_total: 100 | type: Counter 101 | Description: "Total Number of Chain Panic Logs" 102 | prefix: "promtail_chain_panic_" 103 | max_idle_duration: 24h 104 | config: 105 | match_all: true 106 | action: inc 107 | relabel_configs: 108 | - source_labels: ["__journal__systemd_unit"] 109 | target_label: "unit" 110 | - source_labels: ["unit"] 111 | regex: "(.*.scope|user.*.service)" 112 | action: drop 113 | - source_labels: ["__journal__hostname"] 114 | target_label: "host" 115 | - action: replace 116 | source_labels: 117 | - __journal__cmdline 118 | - __journal__hostname 119 | separator: ";" 120 | regex: ".*--chain.*;(.*)" 121 | target_label: "node" 122 | replacement: $1 123 | ``` 124 | 125 | The above example also configures the following custom metrics derived from logs `promtail_chain_log_lines_total`, `promtail_chain_error_log_lines_total` and `promtail_chain_panic_log_lines_total` to be exposed on the promtail metrics endpoint . 126 | 127 | 128 | ### Alerts 129 | 130 | [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) handles alerts sent by Prometheus client, and responsible for deduplicating, grouping and routing to the correct receiver such as email, PagerDuty, and other mechanisms via webhook receiver. 131 | 132 | A simple alert for block production being slow would look like: 133 | 134 | ```yaml 135 | - alert: BlockProductionSlow 136 | annotations: 137 | message: 'Best block on instance {{ $labels.instance }} increases by 138 | less than 1 per minute for more than 5 minutes.' 139 | expr: increase(substrate_block_height{status="best"}[1m]) < 1 140 | for: 5m 141 | labels: 142 | severity: warning 143 | ``` 144 | 145 | ### Visualization 146 | 147 | [Grafana](https://grafana.com/docs/grafana/latest/) is where you can define dashboards to show the time series information that Prometheus is collecting. You just need to ensure you add a datasource: 148 | 149 | ```yaml 150 | datasources: 151 | - name: "Prometheus" 152 | type: prometheus 153 | access: proxy 154 | editable: false 155 | orgId: 1 156 | url: "http://prometheus.monitoring.svc.cluster.local" 157 | version: 1 158 | jsonData: 159 | timeInterval: 30s 160 | - name: Loki 161 | type: loki 162 | access: proxy 163 | orgId: 1 164 | url: http://loki:3100 165 | basicAuth: false 166 | version: 1 167 | editable: true 168 | ``` 169 | 170 | ### Polkadot-mixin 171 | Polkadot-monitoring-mixin is a set of Polkadot monitoring dashboards, alerts and rules collected based on our experience operating Polkadot Relay Chain and Parachain nodes. You can find it in this [repo](https://github.com/paritytech/polkadot-monitoring-mixin). 172 | 173 | ## Docker Compose 174 | 175 | You can install the following components Docker Compose if you are evaluating, or developing monitoring stack for Polkadot. 176 | The configuration files associated with these installation instructions run the monitoring stack as a single binary. 177 | 178 | ``` 179 | version: "3.8" 180 | 181 | networks: 182 | polkadot: 183 | 184 | services: 185 | prometheus: 186 | container_name: prometheus 187 | image: prom/prometheus:v2.53.0 188 | command: 189 | - '--config.file=/etc/prometheus/prometheus.yml' 190 | ports: 191 | - 9090:9090 192 | restart: unless-stopped 193 | configs: 194 | - source: prometheus_config 195 | target: /etc/prometheus/prometheus.yml 196 | networks: 197 | - polkadot 198 | 199 | loki: 200 | container_name: loki 201 | image: grafana/loki:3.1.0 202 | ports: 203 | - "3100:3100" 204 | command: -config.file=/etc/loki/local-config.yaml 205 | networks: 206 | - polkadot 207 | 208 | promtail: 209 | container_name: promtail 210 | image: grafana/promtail:3.1.0 211 | command: -config.file=/etc/promtail/config.yml 212 | user: root # Required to read container logs 213 | ports: 214 | - 9080:9080 215 | volumes: 216 | - /var/lib/docker/containers:/var/lib/docker/containers 217 | - /var/run/docker.sock:/var/run/docker.sock 218 | configs: 219 | - source: promtail_config 220 | target: /etc/promtail/config.yml 221 | networks: 222 | - polkadot 223 | 224 | grafana: 225 | container_name: grafana 226 | image: grafana/grafana:latest 227 | environment: 228 | - GF_PATHS_PROVISIONING=/etc/grafana/provisioning 229 | - GF_AUTH_ANONYMOUS_ENABLED=true 230 | - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin 231 | entrypoint: 232 | - sh 233 | - -euc 234 | - | 235 | mkdir -p /etc/grafana/provisioning/datasources 236 | cat < /etc/grafana/provisioning/datasources/ds.yaml 237 | apiVersion: 1 238 | datasources: 239 | - name: Loki 240 | type: loki 241 | access: proxy 242 | orgId: 1 243 | url: http://loki:3100 244 | basicAuth: false 245 | version: 1 246 | editable: true 247 | - name: Prometheus 248 | type: prometheus 249 | access: proxy 250 | orgId: 1 251 | url: http://prometheus:9090 252 | basicAuth: false 253 | isDefault: true 254 | version: 1 255 | editable: true 256 | EOF 257 | /run.sh 258 | ports: 259 | - "3000:3000" 260 | networks: 261 | - polkadot 262 | 263 | polkadot_collator: 264 | container_name: polkadot_collator 265 | image: parity/polkadot-parachain:1.14.0 266 | command: > 267 | --tmp --prometheus-external --prometheus-port 9625 -- --tmp --prometheus-external --prometheus-port 9615 268 | ports: 269 | - "9615:9615" 270 | - "9625:9625" 271 | networks: 272 | - polkadot 273 | 274 | configs: 275 | prometheus_config: 276 | content: | 277 | global: 278 | scrape_interval: 15s # By default, scrape targets every 15 seconds. 279 | evaluation_interval: 15s # Evaluate rules every 15 seconds. 280 | 281 | scrape_configs: 282 | - job_name: polkadot 283 | static_configs: 284 | - targets: 285 | - polkadot_collator:9615 # relaychain metrics 286 | - polkadot_collator:9625 # parachain metrics 287 | promtail_config: 288 | content: | 289 | server: 290 | http_listen_port: 9080 291 | 292 | positions: 293 | filename: /tmp/positions.yaml 294 | 295 | clients: 296 | - url: http://loki:3100/loki/api/v1/push 297 | 298 | scrape_configs: 299 | - job_name: containers 300 | docker_sd_configs: 301 | - host: unix:///var/run/docker.sock 302 | refresh_interval: 5s 303 | filters: 304 | - name: name 305 | values: [polkadot_collator] 306 | relabel_configs: 307 | - source_labels: ['__meta_docker_container_name'] 308 | regex: '/(.*)' 309 | target_label: 'container' 310 | ``` -------------------------------------------------------------------------------- /src/monitoring/polkadot_sdk.md: -------------------------------------------------------------------------------- 1 | ## On-Host Configuration 2 | The polkadot-sdk binary supports Prometheus metrics, which are exposed at . By default, this endpoint is only available on the local network interface. To expose it on all interfaces, you can use the --prometheus-external flag. However, when running a polkadot-parachain binary, managing the metrics becomes more complex due to two ports being used for different purposes. 3 | 4 | #### Running the Polkadot Binary (Relay Chain) 5 | To run the Polkadot binary with Prometheus metrics exposed, use the following command: 6 | 7 | ``` 8 | ./polkadot --tmp --prometheus-external 9 | ``` 10 | 11 | #### Running the Polkadot-Parachain Binary (Parachain) 12 | For the Polkadot-Parachain binary, use the following command to expose Prometheus metrics on a specified port: 13 | 14 | ``` 15 | ./polkadot-parachain --tmp --prometheus-external --prometheus-port 9625 -- --tmp --prometheus-port 9615 16 | ``` 17 | 18 | As you can see above, running a polkadot-parachain binary can expose two different Prometheus port to ensure separation of metrics between relay chain and parachain. 19 | 20 | #### Common Substrate metrics 21 | 22 | Here is a non-exhaustive lists of useful metrics exposed on the nodes `metrics` endpoint: 23 | 24 | - `substrate_block_height`: the best and finalized block number for this node. This should be increasing when your node is producing or syncing blocks from the network. 25 | - `substrate_sub_libp2p_peers_count`: the number of node peers 26 | - `substrate_sub_txpool_validations_finished`: transactions in the node transaction queue, there should be some but not too high counts which would mean that the transaction are not propagated to other nodes. 27 | - `substrate_sub_libp2p_incoming_connections_total`: this must be constantly increasing especially on validators and collators as those active nodes need to be able to receive incoming connections from other peers. This can be a sign that the node is incorrectly configured to allow p2p access (--listen-addr/--public-addr). 28 | 29 | #### Differences in Metric Labels 30 | 31 | There are key differences in the labels of metrics exposed by the relay chain and parachain binaries: 32 | 33 | *Relay Chain Metrics at Port 9615* 34 | ``` 35 | # TYPE polkadot_memory_allocated gauge 36 | polkadot_memory_allocated{chain="rococo_local_testnet"} 225670544 37 | 38 | # HELP polkadot_memory_resident Bytes allocated by the node, and held in RAM 39 | # TYPE polkadot_memory_resident gauge 40 | polkadot_memory_resident{chain="rococo_local_testnet"} 679718912 41 | 42 | # HELP polkadot_node_is_active_validator Tracks if the validator is in the active set. Updates at session boundary. 43 | # TYPE polkadot_node_is_active_validator gauge 44 | polkadot_node_is_active_validator{chain="rococo_local_testnet"} 0 45 | ``` 46 | 47 | *Parachain Metrics at Port 9625* 48 | ``` 49 | # HELP substrate_block_height Block height info of the chain 50 | # TYPE substrate_block_height gauge 51 | substrate_block_height{status="best",chain="local_testnet"} 0 52 | substrate_block_height{status="finalized",chain="local_testnet"} 0 53 | substrate_block_height{status="sync_target",chain="local_testnet"} 0 54 | ``` 55 | 56 | 57 | #### Best Practices 58 | To avoid confusion caused by running metrics on different ports, it is recommended to maintain uniformity by using the same Prometheus port (default is 9615) for all relay chain metrics. The chain label in the metrics helps determine which metric belongs to which chain, ensuring clarity and organization. 59 | 60 | By following this guide, you can effectively expose and manage Prometheus metrics for both the Polkadot relay chain and parachain binaries. -------------------------------------------------------------------------------- /src/overview.md: -------------------------------------------------------------------------------- 1 | # Overview 2 | 3 | This guide contains the following sections: 4 | 5 | - [How-to guides](./guides/index.md): Getting started with specific use case, eg. deploying a parachain network. 6 | - [Explanations](./explanations/index.md): Explanations of concepts and configurations relevant to Polkadot blockchain infrastructure. 7 | - [References](./references/index.md): Index of useful links and tools. 8 | -------------------------------------------------------------------------------- /src/references/index.md: -------------------------------------------------------------------------------- 1 | # Infrastructure Tooling References 2 | 3 | This section is for listing some useful projects and tools that are relevant for node operators and developers. A community maintained [Awesome Substrate](https://github.com/substrate-developer-hub/awesome-substrate) is a more detailed general list. 4 | 5 | ## Deployment 6 | 7 | | Project | Description | 8 | |-----------------------------------------------------------------------------|------------------------------------------| 9 | | [Parity Helm Charts collection](https://github.com/paritytech/helm-charts) | Parity & Polkadot Helm charts collection | 10 | | [Polkadot Ansible collection](https://github.com/paritytech/ansible-galaxy) | Polkadot Ansible Collection | 11 | 12 | 13 | ## Tooling 14 | 15 | For an up-to-date list of Polkadot related tooling, check the [Polkadot Wiki Tool Index](https://wiki.polkadot.network/docs/build-tools-index). 16 | 17 | ## Indexing Chain Data 18 | 19 | | Project | Description | 20 | | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 21 | | [Substrate archive](https://github.com/paritytech/substrate-archive.git) | Blockchain indexing engine using PostgreSQL | 22 | | [Subsquid](https://github.com/subsquid/squid) | Blockchain indexing engine using GraphQL | 23 | | [SubQuery](https://academy.subquery.network/) | Open source GraphQL indexing of any Substrate network (including EVM and WASM smart contract data) directly from the RPC node. SubQuery does not require any preprocessed data making it suitable for fast changing testnets | 24 | 25 | ## CLI Utilities 26 | 27 | | Project | Description | 28 | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | 29 | | [Subkey](https://github.com/paritytech/substrate/tree/master/bin/utils/subkey) | Used for generating and restoring keys. Works with multiple networks and key schemes | 30 | | [polkadot-js-tools](https://github.com/polkadot-js/tools) | A very flexible utility for executing API calls or running queries. | 31 | | [Subxt](https://github.com/paritytech/subxt) | Submits extrinsics via RPC | 32 | 33 | ## Monitoring 34 | 35 | | Project | Description | 36 | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | 37 | | [Polkabot](https://gitlab.com/Polkabot/polkabot) | Polkabot is a Matrix chatbot that keeps an eye on the Polkadot network. | 38 | | [polkadot-watcher-transaction](https://github.com/w3f/polkadot-watcher-transaction) | The main use case of this application consits of a scanner that can be configured to start from a configured block number, and then it keeps monitoring the on-chain situation delivering alerts to a notifier. | 39 | | [polkadot-watcher-validator](https://github.com/w3f/polkadot-watcher-validator) | The watcher is a nodeJs application meant to be connected with a substrate based node through a web socket. It can then monitor the status of the node, leveraging on mechanisms such as the builtin heartbeat. | 40 | | [polkadot-k8s-payouts](https://github.com/w3f/polkadot-k8s-payouts) | Tool that automatically claims your Kusama/Polkadot validator rewards. | 41 | 42 | -------------------------------------------------------------------------------- /src/serverdeploy/automation.md: -------------------------------------------------------------------------------- 1 | # Automation 2 | 3 | ## Cloud Provisioning 4 | 5 | There are multiple options to provision cloud resources, which can either be provider specific and some tools are more cloud-agnostic. 6 | 7 | ### Popular Cloud Provider Specific Deployment Tooling 8 | 9 | - [Amazon Cloud Formation](https://aws.amazon.com/cloudformation/) 10 | - [Azure Resource Manager](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview) 11 | - [Google Cloud Deployment](https://cloud.google.com/deployment-manager/docs) 12 | 13 | These vendor specific deployment tools are easy to use, have great examples and support. However, when using multiple providers with custom scripting formats, making a basic to your infrastructure can require changes to multiple sections of code, for each provider to do the same thing (e.g. open a port on a host). 14 | 15 | A more general solution where a change can be specified once and be used with multiple providers is using Terraform. Which currently has [more than](https://registry.terraform.io/browse/providers) 2000 providers supported. 16 | 17 | ## Terraform 18 | 19 | [Terraform](https://www.terraform.io/) is a very commonly used tool for creating all sorts of cloud resources. It supports many different providers along with having excellent modules for the main three providers (AWS, Azure, GCP). Many projects rely on this for their infrastructure deployments. 20 | 21 | It uses HashiCorp’s [HashiCorp Configuration Language](https://www.terraform.io/language), which makes it very easy to abstract configuration, avoid the reuse of code and enables you to plug modules together easily (e.g. RPC nodes along with a frontend load balancer). 22 | 23 | The code is also easy to read and should be in version control. Multiple environments can be defined, so you can ensure you are using the same code on dev / test / production. 24 | 25 | Two ways to preconfigure your host after deployment using terraform directly is to either: 26 | 27 | - Use a pre-packaged image with all of your software (e.g. packer or similar tooling) 28 | - Use a cloud-init script to execute a certain script to preconfigure your base image 29 | 30 | Some examples of using terraform with multiple providers can be found in the W3F’s polkadot-validator-setup GitHub repo. 31 | 32 | Click here for a list of [terraform providers](https://registry.terraform.io/browse/providers). 33 | 34 | ### Host Maintenance 35 | 36 | Once your hosts are deployed you will need to configure the hosts and install the required software, configuration files etc… As mentioned this can be done in a few ways using terraform itself, however another very flexible way of configuring hosts is using Ansible. 37 | 38 | | Component | Description | 39 | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 40 | | Playbook | Playbooks are the language by which Ansible orchestrates, configures, administers, or deploys systems | 41 | | Role | Roles are units of organization in Ansible. Assigning a role to a group of hosts (or a set of groups, or host patterns, and so on) implies that they should implement a specific behavior | 42 | 43 | When deploying our blockchain nodes, we will need an inventory which contains a list of our hosts and the groups they are in (e.g. validator, collator, rpc) and maybe some secrets which can be encrypted inline within the inventory using [Ansible vault](https://docs.ansible.com/ansible/latest/user_guide/vault.html). We will then call a playbook which links hosts/groups in the inventory with roles to execute on each host. 44 | 45 | Some examples of using Ansible can be found in the Paritytech's [Ansible Galaxy](https://github.com/paritytech/ansible-galaxy) GitHub repo. Specifically the node role. 46 | -------------------------------------------------------------------------------- /src/serverdeploy/index.md: -------------------------------------------------------------------------------- 1 | # Server Deployments 2 | -------------------------------------------------------------------------------- /src/serverdeploy/logging.md: -------------------------------------------------------------------------------- 1 | # Logging 2 | 3 | ## Local Logging 4 | 5 | By default, output from your systemd service will go to local syslog. This will mean it ends up in a place like `/var/log/syslog` or `/var/log/messages` 6 | 7 | You can also view these using the `journalctl` command. To tail the current output of the polkadot process run: 8 | 9 | ```bash 10 | journalctl -u polkadot -f 11 | ``` 12 | 13 | It is also possible to remove old logs (say older than two days ago) using a command: 14 | 15 | ```bash 16 | journalctl -u polkadot --vacuum-time=2d 17 | ``` 18 | 19 | Or to retain only the past 1G of data run: 20 | 21 | ```bash 22 | journalctl --vacuum-size=1G 23 | ``` 24 | 25 | ## Remote Logging 26 | 27 | In a setup with many hosts you will want to aggregate the logs at a central point, some common options include Loki or Elasticsearch. 28 | 29 | ### Loki 30 | 31 | To log to a remote Loki instance you need to install the `promtail` package. An example configuration file to send logs to a remote host: 32 | 33 | ```yaml 34 | # promtail server config 35 | server: 36 | http_listen_port: 9080 37 | grpc_listen_port: 0 38 | log_level: info 39 | positions: 40 | filename: /var/lib/promtail/positions.yaml 41 | 42 | # loki servers 43 | clients: 44 | - url: http://myloki.mycompany.com/loki/api/v1/push 45 | backoff_config: 46 | min_period: 1m 47 | max_period: 1h 48 | max_retries: 10000 49 | scrape_configs: 50 | - job_name: journald 51 | journal: 52 | max_age: 1m 53 | path: /var/log/journal 54 | labels: 55 | job: journald 56 | pipeline_stages: 57 | - match: 58 | selector: '{job="journald"}' 59 | stages: 60 | - multiline: 61 | firstline: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}' 62 | max_lines: 2500 63 | - regex: 64 | expression: '(?P\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3})\s+(?P(TRACE|DEBUG|INFO|WARN|ERROR))\s+(?P([^\s]+))\s+(?P[\w-]+):?:?(?P[\w-]+)?:[\s]?(?P\[[\w-]+\]+)?[\s]?(?P.+)' 65 | - labels: 66 | level: 67 | target: 68 | subtarget: 69 | ``` 70 | 71 | ### Elasticsearch 72 | 73 | To log to a remote Elasticsearch cluster you need to install the `logstash` package. An example configuration would look like: 74 | 75 | <<<<<<< HEAD 76 | ```json 77 | input { 78 | journald { 79 | path => "/var/log/journal" 80 | seekto => "tail" 81 | thisboot => true 82 | filter => { 83 | "_SYSTEMD_UNIT" => "polkadot.service" 84 | } 85 | type => "systemd" 86 | } 87 | ======= 88 | 89 | ```yaml 90 | input { 91 | journald { 92 | path => "/var/log/journal" 93 | seekto => "tail" 94 | thisboot => true 95 | filter => { 96 | "_SYSTEMD_UNIT" => "polkadot.service" 97 | } 98 | type => "systemd" 99 | } 100 | >>>>>>> main 101 | } 102 | 103 | 104 | filter { 105 | date { 106 | match => ["timestamp", "YYYY-mm-dd HH:MM:ss.SSS"] 107 | target => "@timestamp" 108 | } 109 | mutate { 110 | rename => [ "MESSAGE", "message" ] 111 | remove_field => [ "cursor", "PRIORITY", "SYSLOG_FACILITY", "SYSLOG_IDENTIFIER", "_BOOT_ID", "_CAP_EFFECTIVE", "_CMDLINE", "_COMM", "_EXE", "_GID", "_HOSTNAME", "_MACHINE_ID", "_PID", "_SELINUX_CONTEXT", "_STREAM_ID", "_SYSTEMD_CGROUP", "_SYSTEMD_INVOCATION_ID", "_SYSTEMD_SLICE", "_SYSTEMD_UNIT", "_TRANSPORT", "_UID" ] 112 | } 113 | if ([message] =~ ".*TRACE .*") { drop{ } } 114 | grok { 115 | match => { "message" => "%{NOTSPACE:thread} %{LOGLEVEL:log-level} %{NOTSPACE:namespace} %{GREEDYDATA:message}" } 116 | } 117 | } 118 | 119 | output { 120 | elasticsearch { 121 | hosts => ["https://myelasticsearch.mycompany.com:9243"] 122 | user => "username" 123 | password => "password" 124 | index => "logstash-polkadot-%{+YYYY.MM.dd}" 125 | } 126 | } 127 | ``` 128 | 129 | ## Logging Options 130 | 131 | Logging output from any substrate based changes has many log levels and targets. All targets are set to `info` logging by default. You can adjust individual log levels using the `--log (-l short)` option, for example `-l afg=trace,sync=debug` or globally with `-ldebug`. 132 | 133 | Levels: 134 | 135 | - error 136 | - warn 137 | - info 138 | - debug 139 | - trace 140 | 141 | Targets: 142 | 143 | - afg 144 | - aura 145 | - babe 146 | - beefy 147 | - db 148 | - gossip 149 | - header 150 | - peerset 151 | - pow 152 | - rpc 153 | - runtime 154 | - runtime::contracts 155 | - sc_offchain 156 | - slots 157 | - state-db 158 | - state_tracing 159 | - sub-libp2p 160 | - sync 161 | - telemetry 162 | - tracing 163 | - trie 164 | - txpool 165 | -------------------------------------------------------------------------------- /src/serverdeploy/systemd.md: -------------------------------------------------------------------------------- 1 | # Systemd 2 | 3 | ## Overview 4 | 5 | Systemd is a common way to manage services on Linux hosts. It can ensure the process is enabled and running, allows you to set a policy for restarts and also set the user running the host, limit the memory usage etc... 6 | 7 | It can also use an environment variable file which can help abstract the variables into its own file per server. 8 | 9 | ## Simple Example 10 | 11 | A simple example running a local dev chain as Alice, assuming the username is called polkadot would look like: 12 | 13 | ```yaml 14 | [Unit] 15 | Description=Polkadot Validator 16 | 17 | [Service] 18 | User=polkadot 19 | ExecStart=/home/polkadot/polkadot --dev --alice 20 | Restart=always 21 | RestartSec=90 22 | 23 | [Install] 24 | WantedBy=multi-user.target 25 | ``` 26 | 27 | This file should be placed in /etc/systemd/system/polkadot.service and then enabled with `systemctl enable polkadot` then `systemctl start polkadot` to start the service. 28 | 29 | ## Using Environment Variable Files 30 | 31 | If we want to remove some options from the systemd file itself (e.g. `--dev --alice`) and put them in an environment variable file then the systemd service would now look like: 32 | 33 | ```yaml 34 | [Unit] 35 | Description=Polkadot Validator 36 | 37 | [Service] 38 | User=polkadot 39 | EnvironmentFile=/etc/default/polkadot 40 | ExecStart=/home/polkadot/polkadot $START_OPTIONS 41 | Restart=always 42 | RestartSec=90 43 | 44 | [Install] 45 | WantedBy=multi-user.target 46 | ``` 47 | 48 | Then you would need to create a file in /etc/default/polkadot which looks like: 49 | 50 | ```bash 51 | START_OPTIONS="--dev --alice" 52 | ``` 53 | 54 | You can do this with multiple variables to abstract the configuration from the systemd file running on your hosts. 55 | --------------------------------------------------------------------------------