Skip to content

Commit

Permalink
1. Split guild-deploy option for force overwrite of config and scripts
Browse files Browse the repository at this point in the history 
2. Update node-cli documentation to include sample topology.json for Core node
3. Update upgrade.md for generic instructions and update basics.md for guild-deploy updates
4. Rename valency to hotValency in topology samples as valency is supposedly deprecated
  • Loading branch information
@rdlrt
rdlrt committed Jul 26, 2024
1 parent 00607ab commit 5b74809
Show file tree
Hide file tree
Showing 10 changed files with 140 additions and 110 deletions.
51 changes: 41 additions & 10 deletions docs/Build/node-cli.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
!!! info "Reminder !!"
Unless there is a very particular reason you want to compile (eg: running on non-popular OS flavor), you DO NOT "need" to build node binaries - `guild-deploy.sh` already provides an option to download pre-compiled binaries.
Ensure the [Pre-Requisites](../basics.md#pre-requisites) are in place before you proceed.

### Build Instructions
Expand Down Expand Up @@ -40,10 +41,10 @@ Execute `cardano-cli` and `cardano-node` to verify output as below (the exact ve

```bash
cardano-cli version
# cardano-cli 8.x.x - linux-x86_64 - ghc-8.10
# cardano-cli 9.x.x - linux-x86_64 - ghc-8.10
# git rev <...>
cardano-node version
# cardano-node 8.x.x - linux-x86_64 - ghc-8.10
# cardano-node 9.x.x - linux-x86_64 - ghc-8.10
# git rev <...>
```

Expand Down Expand Up @@ -106,7 +107,7 @@ This file tells your node how to connect to other nodes (especially initially to
!!! important
On BP, You'd want to set `useLedgerAfterSlot` to `-1` for your Block Producing (Core) node - thereby, telling your Core node to remain in non-P2P mode, and ensure `PeerSharing` is to `false`.

The resultant topology file could look something like below:
The resultant topology file on a relay could look something like below:

``` json
{
Expand All @@ -118,25 +119,29 @@ The resultant topology file could look something like below:
{
"address": "backbone.mainnet.emurgornd.com",
"port": 3001
},
{
"address": "backbone.mainnet.cardanofoundation.org",
"port": 3001
}
],
"localRoots": [
{
"accessPoints": [
{"address": "xx.xx.xx.xx", "port": 6000 },
{"address": "xx.xx.xx.yy", "port": 6000 }
{"address": "xx.xx.xx.xx", "port": 6000 , "description": "Core"},
{"address": "zz.zz.zz.zz", "port": 6000 , "description": "Relay2"}
],
"advertise": false,
"trustable": true,
"valency": 2
"hotValency": 2
},
{
"accessPoints": [
{"address": "node-dus.poolunder.com", "port": 6900, "pool": "UNDR", "location": "EU/DE/Dusseldorf" },
{"address": "node-syd.poolunder.com", "port": 6900, "pool": "UNDR", "location": "OC/AU/Sydney" },
{"address": "194.36.145.157", "port": 6000, "pool": "RDLRT", "location": "EU/DE/Baden" },
{"address": "152.53.18.60", "port": 6000, "pool": "RDLRT", "location": "NA/US/StLouis" },
{"address": "148.72.153.168", "port": 16000, "pool": "AAA", "location": "US/StLouis" },
{"address": "95.216.38.251", "port": 6000, "pool": "RDLRT", "location": "EU/FI/Helsinki" },
{"address": "148.72.153.168", "port": 16000, "pool": "AAA", "location": "NA/US/StLouis" },
{"address": "78.47.99.41", "port": 6000, "pool": "AAA", "location": "EU/DE/Nuremberg" },
{"address": "relay1-pub.ahlnet.nu", "port": 2111, "pool": "AHL", "location": "EU/SE/Malmo" },
{"address": "relay2-pub.ahlnet.nu", "port": 2111, "pool": "AHL", "location": "EU/SE/Malmo" },
Expand All @@ -146,7 +151,7 @@ The resultant topology file could look something like below:
],
"advertise": false,
"trustable": false,
"valency": 5,
"hotValency": 5,
"warmValency": 10
}
],
Expand All @@ -156,7 +161,33 @@ The resultant topology file could look something like below:
"advertise": false
}
],
"useLedgerAfterSlot": 119160667
"useLedgerAfterSlot": 128908821
}
```

Similarly, a typical topology file on a Core could look something like below:

``` json
{
"bootstrapPeers": [],
"localRoots": [
{
"accessPoints": [
{"address": "yy.yy.yy.yy", "port": 6000, "description": "Relay1"},
{"address": "zz.zz.zz.zz", "port": 6000, "description": "Relay2"}
],
"advertise": false,
"trustable": true,
"hotValency": 2
}
],
"publicRoots": [
{
"accessPoints": [],
"advertise": false
}
],
"useLedgerAfterSlot": -1
}
```

Expand Down
30 changes: 17 additions & 13 deletions docs/basics.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,18 +8,19 @@ The architecture for various components are already described at [docs.cardano.o
While we do not intend to hand out step-by-step instructions, the tools are often misused as a shortcut to avoid ensuring base skillsets mentioned on home page. Some of the common gotchas that we often find SPOs to miss out on:

- It is imperative that pools operate with highly accurate system time, in order to propogate blocks to network in a timely manner and avoid penalties to own (or at times other competing) blocks. Please refer to sample guidance [here ](https://ubuntu.com/server/docs/network-ntp) for details - the precise steps may depend on your OS.
- Ensure your Firewall rules at Network as well as OS level are updated according to the usage of your system, you'd want to whitelist the rules that you really need to open to world (eg: You might need node, SSH, and potentially secured webserver/proxy ports to be open, depending on components you run).
- Ensure your Firewall rules at Network as well as OS level are updated according to the usage of your system, you'd want to whitelist the rules that you really need to open to world (eg: You might need node and SSH ports to be open to relays and perhaps home workstation on core, while open node to internet on relays, depending on your topology and configuration that you run).
- Update your SSH Configuration to prevent password-based logon.
- Ensure that you use offline workflow, you should never require to have your offline keys on online nodes. The tools provide you backup/restore functionality to only pass online keys to online nodes.

#### Pre-Requisites

!!! info "Reminder !!"
You're expected to run the commands below from same session, using same working directories as indicated and using a `non-root user with sudo access`. You are expected to be familiar with this as part of pre-requisite skill sets for stake pool operators.
You're expected to run the commands below from same session, using same working directories as indicated and using a `non-root user with sudo access`. You are expected to be familiar with this as part of pre-requisite skill sets for stake pool operators.

##### Set up OS packages, folder structure and fetch files from repo {: #os-prereqs}

The pre-requisites for Linux systems are automated to be executed as a single script. To download the pre-requisites scripts, execute the below:
The pre-requisites for Linux systems are automated to be executed as a single script. This script uses opt-in election of what you'd like the script to do. The defaults without any arguments will only update static part of script contents for you.
To download the pre-requisites scripts, execute the below:

```bash
mkdir "$HOME/tmp";cd "$HOME/tmp"
Expand All @@ -30,11 +31,14 @@ curl -sS -o guild-deploy.sh https://raw.githubusercontent.com/cardano-community/
chmod 755 guild-deploy.sh
```

Please familiarise with the syntax of `guild-deploy.sh` before proceeding. The usage syntax can be checked using `./guild-deploy.sh -h` , sample output below:
!!! info "Important !!"
Please familiarise with the syntax of `guild-deploy.sh` before proceeding (using -h as below). The exact parameters you want to run with is dependent on your, below are only sample instructions

The usage syntax can be checked using `./guild-deploy.sh -h` , sample output below:

``` bash

Usage: guild-deploy.sh [-n <mainnet|preprod|guild|preview>] [-p path] [-t <name>] [-b <branch>] [-u] [-s [p][b][l][m][f][d][c][o][w][x]]
Usage: guild-deploy.sh [-n <mainnet|guild|preprod|preview|sanchonet>] [-p path] [-t <name>] [-b <branch>] [-u] [-s [p][b][l][m][d][c][o][w][x][f][s]]
Set up dependencies for building/using common tools across cardano ecosystem.
The script will always update dynamic content from existing scripts retaining existing user variables

Expand All @@ -48,18 +52,18 @@ The script will always update dynamic content from existing scripts retaining ex
b Install OS level dependencies for tools required while building cardano-node/cardano-db-sync components (Default: skip)
l Build and Install libsodium fork from IO repositories (Default: skip)
m Download latest (released) binaries for mithril-signer, mithril-client (Default: skip)
f Force overwrite entire content of scripts and config files (backups of existing ones will be created) (Default: skip)
d Download latest (released) binaries for bech32, cardano-address, cardano-node, cardano-cli, cardano-db-sync and cardano-submit-api binaries (Default: skip)
c Install/Upgrade CNCLI binary (Default: skip) # (1)!
o Install/Upgrade Ogmios Server binary (Default: skip)
w Install/Upgrade Cardano Hardware CLI (Default: skip)
x Install/Upgrade Cardano Signer binary (Default: skip)
d Download latest (released) binaries for bech32, cardano-address, cardano-node, cardano-cli, cardano-db-sync and cardano-submit-api (Default: skip)
c Download latest (released) binaries for CNCLI (Default: skip)
o Download latest (released) binaries for Ogmios (Default: skip)
w Download latest (released) binaries for Cardano Hardware CLI (Default: skip)
x Download latest (released) binaries for Cardano Signer binary (Default: skip)
f Force overwrite config files (backups of existing ones will be created) (Default: skip)
s Force overwrite entire content [including user variables] of scripts (Default: skip)

```
1. If you receive an error for `glibc`, it would likely be due to the build mismatch between pre-compiled binary and your OS, which is not uncommon. You may need to compile cncli manually on your OS as per instructions [here](https://github.com/cardano-community/cncli/blob/develop/INSTALL.md#compile-from-source) - make sure to copy the output binary to `"${HOME}/.local/bin"` folder.
This script uses opt-in election of what you'd like the script to do (as against previous version that used to try and auto-detect versions). The defaults without any arguments will only update static part of script contents for you.
A typical example install to install most components but not overwrite static part of existing files for preview network would be:
``` bash
Expand All @@ -82,7 +86,7 @@ Lastly, if you'd want to update your scripts but not install any additional depe
##### Folder structure
Running the script above will create the folder structure as per below, for your reference. You can replace the top level folder `/opt/cardano/cnode` by editing the value of `CNODE_HOME` in `~/.bashrc` and `$CNODE_HOME/files/env` files:
Running the script above will create the folder structure as per below, for your reference. You do NOT require `CNODE_HOME` to be set on shell level as scripts will derive the parent folder and assign it at runtime, the addition in `~/.bashrc` is only for your ease to switch to right folder:
/opt/cardano/cnode # Top-Level Folder
Expand Down
Loading

0 comments on commit 5b74809

Please sign in to comment.