Merge pull request #32 from XinFinOrg/develop

update docs for Subnet Configuration Generator v1

.github/workflows/docusaurus-deploy-develop.yml

@@ -1,7 +1,7 @@
 on:
   push:
     branches:
-      - main 
+      - develop
 
 jobs:
   deploy:
@@ -14,11 +14,15 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v2
         with:
-          node-version: 18 
+          node-version: 18
 
       - name: Install dependencies
         run: npm install
 
+      - name: reconfig docusaurus baseUrl
+        run: |
+          sed -i 's|baseUrl: '\''/xdc-subnet-docs/'\''|baseUrl: '\''/xdc-subnet-docs/develop/'\''|' docusaurus.config.js
+
       - name: Build site
         run: npm run build
 
@@ -27,4 +31,5 @@ jobs:
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./build
-          publish_branch: gh-pages
+          publish_branch: gh-pages
+          destination_dir: develop

.github/workflows/docusaurus-deploy-main.yml

@@ -1,7 +1,7 @@
 on:
   push:
     branches:
-      - develop
+      - main 
 
 jobs:
   deploy:
@@ -14,7 +14,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v2
         with:
-          node-version: 18
+          node-version: 18 
 
       - name: Install dependencies
         run: npm install
@@ -27,5 +27,4 @@ jobs:
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./build
-          publish_branch: gh-pages
-          destination_dir: develop
+          publish_branch: gh-pages

.gitignore

@@ -1,4 +1,4 @@
 node_modules/
 .docusaurus
-
+.DS_Store
 build

docs/contact.md

@@ -0,0 +1,11 @@
+---
+sidebar_label: "Contact"
+sidebar_position: 7
+---
+
+# Contact Us
+
+For feedback, bug report, request, or general Subnet discussion please feel free to make a post on [XDC Forum](https://forum.xinfin.org/) or [GitHub Issues](https://github.com/XinFinOrg/XDC-Subnet/issues)
+
+
+For troubleshooting, you can talk to us at [Telegram Support Group](./deployment/3_troubleshooting.md#telegram-troubleshooting-support-group) and we will check as soon as possible.

docs/deployment/1_launch_subnet.md

@@ -5,58 +5,70 @@ sidebar_position: 1
 
 # Launch a Subnet
 
-## Overview
-  For the convenience of deploying Subnet, we have provided the Subnet Deployment Generator. The Subnet Deployment Generator is configuration generator for all components of subnet deployment. It generates all the necessary files and configs from a simple initial docker.env file. The required parameters are 
-
-    1. How many machines will you use to deploy subnet?
-    2. How many subnet nodes will you deploy in total?
-    3. IP address of the main machine
-    4. Parentchain wallet with funds
-
-  In this setup the main machine (machine1) will host all the subnet services(relayer, stats, frontend) while the subnet miner nodes will be spread out among all machines.
-
-  The IP address of the main machine is needed for subnet connectivity, this is the IP that is known to all other machines, could be private or public (preferrably private)
-
-  Once generated, the commands to startup the subnet is also provided as a generated `commands.txt` file.
-
-  The deployment is docker based, the main deployment file is `docker-compose.yml`. The `docker-compose.env` is the injection point to all configs. Then, ENVs for the services and subnet nodes are in `*.env` files. Other files include `genesis.json` file to initialize subnet chain, `deployment.json` to deploy the checkpoint smartcontract, and `keys.json` the keypairs for subnet nodes + grandmaster node. Again, these files will be generated by the Subnet Deployment Generator (SDG).
-
 ## Requirements
-  - OS: Linux. Only Linux is supported for full deployment. 
+  - OS: Linux. Only Linux is supported for full deployment.
 
-  - OS: Mac is only supported for single machine testing environment. Specify MacOS with 'OS=mac' in 'docker.env' file. Please also refer [common issues](./2_debug_guide.md#common-issues).
+  - OS: Mac is only supported for single machine testing environment.
 
   - docker, docker compose V2. For manual installation of docker compose V2 please refer to: https://docs.docker.com/compose/install/linux/
 
-## Steps
-  1. Create a `docker.env` file with parameters similar to [`docker.env.example`](https://github.com/XinFinOrg/XinFin-Node/blob/master/subnet/deployment-generator/script/docker.env.example). Detailed parameters explanation [here](./3_configs_explanation.md).
+  - Recommended Hardware (per single Subnet node):
+    - CPU: 2 Core
+    - Memory: 4 GB
+
+  - Web3 wallet with funds. For testing we have faucets provided:
+    - https://faucet.apothem.network/ 
+    - https://faucet.blocksscan.io/
 
-  2. Pull the `generator.sh` script from the generator Github repo
+## Video Walkthrough
+<iframe width="720" height="400" src="https://www.youtube.com/embed/m-sPbMrB8ow" frameborder="0" allow="fullscreen"></iframe>
+
+## Generate Subnet Configs With UI
+
+  1. Pull `generator.sh` script from the generator Github repo
   ```
-  curl -O https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/subnet/deployment-generator/script/generate.sh
+  curl -O https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/subnet/deployment-generator/scripts/generate.sh
   ```
 
-  3. Generate configurations, this will create a new `generated` directory
+  2. Run the configuration generator, this will start a local webserver
   ```
   chmod +x generate.sh
   ./generate.sh
   cd generated
   ```
 
-  4. follow the generated instructions in `commands.txt` to start Subnet Nodes and [make sure they are mining](./2_debug_guide.md#subnet-nodes).
+  3. Go to [http://localhost:5210/](http://localhost:5210) in your browser.
+  <details>
+  <summary>If you are running this on a remote server.</summary>
+  <p>
+    first use ssh tunnel: <code>ssh -N -L localhost:5210:localhost:5210 USERNAME@IP_ADDRESS -i SERVER_KEY_FILE</code>
+  </p>
+  </details>
+
 
-  5. follow the generated instructions in `commands.txt` to deploy the upgradable Checkpoint Smart Contract(CSC). If CSC deployment was successful, you should see CSC addresses in `common.env`, the added ENVs include `PROXY_GATEWAY`, `FULL_CSC`, `LITE_CSC`, `CHECKPOINT_CONTRACT`.
+  4. Config the Subnet options per your requirement.
+  ![UI](./img/ui.png)
 
-  6. follow the generated instructions in `commands.txt` to start the Subnet Services (relayer, stats-server, frontend)
+  5. follow the generated instructions in `commands.txt`. In general, the steps are:
+      - start Subnet Nodes
+      - deploy CSC
+      - deploy XDC-Zero (optional)
+      - start Subnet Services (relayer, stats-server, frontend)
 
-  7. Check out the Subnet UI at `<MAIN_IP>:5555`
+  6. Once successfully deployed, you can check out [UI usage guide](../usage/ui/1_homepage.md)
 
-### Removing Subnet
-  1.  Change the commands in `commands.txt` to `docker compose ... down`
+## Removing Subnet
+
+  ### Shutdown Subnet
+  Under `generated` directory
   ```
-  docker compose --env-file docker-compose.env --profile <profile_name> down 
+  docker compose --env-file docker-compose.env --profile services down 
+  docker compose --env-file docker-compose.env --profile machine1 down
   ```
 
-  2. Repeat 1. for every docker `--profile` that was started. 
-
-  3. Inside `generated` directory, remove `bootnodes`, `stats-service`, and `xdcchain*` directories
+  ### Deleting Subnet 
+  Remove `xdcchain*`, `bootnodes`, and `stats-service` directories
+  Warning: this cannot be undone
+  ``` 
+  rm -rf xdcchain* bootnodes stats-service
+  ```

docs/deployment/2_configs_explanation.md

@@ -0,0 +1,94 @@
+---
+sidebar_label: "2. Configs Explanation"
+sidebar_position: 2
+---
+
+# Configs Explanation
+
+## Files under 'generated' directory 
+After the generator has succesfully run, all generated files will be under 'generated' directory. These files can be edited if you would like to further customize your subnet. Below is a description of each generated file and how it is used.
+
+- commands.txt - The generated instructions to launch the subnet.
+- common.env - The config parameters for Subnet services.
+- contract_deploy.env - The config file used for CSC deployment.
+- subnet*.env - The config parameters for each Subnet node.
+- genesis.json - The 'block 0' of the Subnet. Initializes the blockchain for subnet nodes.
+- genesis_input.yml - An intermediate file used in config generation.
+- keys.json - Generated keypairs or custom keypairs by user input. Please be mindful to keep the credentials secure.
+- docker-compose.yml - The main deployment file. Includes docker images versions, startup commands, network configurations.
+- docker-compose.env - The config injection path that docker uses to point to other *.env files.
+
+### common.env
+- PARENTNET_URL - RPC of the parentnet
+- SUBNET_URL - RPC of the Subnet
+- PARENTNET_WALLET - Public key of the Relayer wallet
+- PARENTNET_WALLET_PK - Private key of the Relayer wallet
+- VITE_SUBNET_URL - URL of stats server backend that is passed to your local browser
+- VITE_SUBNET_RPC - URL of the Subnet RPC that is passed to your local browser
+- CHECKPOINT_CONTRACT - Checkpoint Smart Contract address
+- STATS_SECRET - Secret used by stats server backend
+- EXTIP - Configured IP of bootnode
+- BOOTNODE_PORT - Configured port of bootnode
+
+### subnet*.env
+- INSTANCE_NAME - Subnet node name
+- PRIVATE_KEY - Subnet node private key
+- BOOTNODES - Subnet bootnode to connect and discover other Subnet nodes
+- NETWORK_ID - Subnet network ID
+- SYNC_MODE - Node operation mode (full or archive)
+- RPC_API - enabled api's scheme such as eth, xdpos, debug, net
+- STATS_SERVICE_ADDRESS - Stats server backend URL
+- STATS_SECRET - Secret to authenticate with Stats server
+- PORT - Subnet node port for communication with other Subnet nodes
+- RPCPORT - Subnet node port for accepting RPC calls
+- WSPORT -  Subnet node port for accepting Websocket connections
+- LOG_LEVEL - Desired logging level. 2=Warn, 3=Info, 4=Debug.
+
+
+
+## Subnet Ports
+1. Subnet Nodes - 3 ports are used per each subnet, RPC port, WS port, and Peering port. The port number is incremented by 1 for the next subnet node. For example subnet1's RPC is 8545, subnet2's RPC will be 8546 and so on.
+  - RPC PORT - 8545, 8546, 8547, ... This is the API port, for outside chain communication to issue transaction or query chaindata.
+  - WS PORT - 9555, 9556, 9557, ... This is not used currently.
+  - Peering port - 20303, 20304, 20305, ... This is used for subnet nodes and bootnode peering and communication.
+  - Subnet ports config can be changed in `subnetX.env` for each individual subnet.
+2. Bootnode - port 20301
+  - Bootnode port can be changed at `BOOTNODE_PORT` under `common.env`. Also in each `subnetX.env`, `BOOTNODES` port has to be changed.
+3. Stats Server (UI backend) - port 5213. 
+4. UI Frontend - port 5214.
+5. Relayer UI - port 5215.
+6. Faucet Server - port 5211
+7. Generator UI - port 5210.
+<!-- 7. Explorer UI - port -->
+
+
+## Updating Configs
+### Upgrading Subnet Deployment
+#### Create a Subnet backup
+1. [Shutdown the subnet](./1_launch_subnet.md#shutdown-subnet )
+
+2. Make a copy of `xdcchain` directory
+
+#### Update Subnet Versions
+1. Go to `docker-compose.yml` under `generated` directory. 
+2. Change the docker image tag of your desired component(s).
+3. Run:
+```
+  docker compose --env-file docker-compose.env --profile machine1 up -d
+  docker compose --env-file docker-compose.env --profile services up -d
+```
+
+Using `latest` tag is not recommended since not all components version are not guaranteed to be compatible.
+
+### Updating Services Configs
+1. Shut down subnet services
+```
+docker compose --env-file docker-compose.env --profile services down
+```
+2. Update configuration (usually ENVs inside common.env file)
+
+3. Start subnet services
+```
+docker compose --env-file docker-compose.env --profile services up -d
+```
+