└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # ARK Core cheatsheet 2 | 3 | > A curated list with useful commands, links and answers to common issues / questions for delegates and relay node operators 4 | 5 | ## Contents 6 | 7 | * [Basics](#basics) 8 | * [Updating Server](#updating-server) 9 | * [Fresh ARK Core 2.2 Install](#fresh-ark-core-22-install) 10 | * [SSH Access](#ssh-access) 11 | * [Useful aliases](#useful-aliases) 12 | * [Security](#security) 13 | * [Node Configuration](#node-configuration) 14 | * [Plugins / Scripts](#plugins--scripts) 15 | * [.env File](#env-file) 16 | * [Snapshots](#snapshots) 17 | * [Creating a Snapshot](#creating-a-snapshot) 18 | * [Restoring from a Snapshot](#restoring-from-a-snapshot) 19 | * [Rollback](#rollback) 20 | * [Database Dump](#database-dump) 21 | * [Sharing a Snapshot](#sharing-a-snapshot) 22 | * [Misc](#misc) 23 | * [Core File Locations](#core-file-locations) 24 | * [Disabling API Ratelimit](#disabling-api-ratelimit) 25 | * [Whitelisting IPs](#whitelisting-ips) 26 | * [Getting logs from server](#getting-logs-from-server) 27 | * [Common Issues / FAQ](#common-issues--faq) 28 | * [Removing Processes from PM2](#removing-processes-from-pm2) 29 | * [Process Showing "Errored"](#process-showing-errored) 30 | * [Cannot find module ...](#cannot-find-module) 31 | * [The "..." process has entered an unknown state](#the-process-has-entered-an-unknown-state) 32 | * [Useful Links](#useful-links) 33 | 34 | ---- 35 | 36 | ## Basics 37 | 38 | ### Updating Server 39 | 40 | Install and enable the latest security patches and updates: 41 | 42 | ```bash 43 | sudo apt-get update -y 44 | sudo apt-get upgrade -y 45 | sudo reboot 46 | ``` 47 | 48 | ### Fresh ARK Core 2.2 Install 49 | 50 | For a fresh installation of Core 2.2, you can read the instructions in the [official ARK docs](https://docs.ark.io/guidebook/core/cli.html#fresh-installation). In short, it comes down to running the following commands: 51 | 52 | ```bash 53 | adduser ark 54 | usermod -aG sudo ark 55 | su ark 56 | cd ~ 57 | bash <(curl -s https://raw.githubusercontent.com/ArkEcosystem/core/master/install.sh) 58 | ``` 59 | 60 | ### SSH Access 61 | 62 | Depending on your server provider, you can often configure an SSH key in their web portal. That is the most convenient way, as your SSH key will then be available on any server you create with them. If you don't have this option, or want to set it up manually anyway, read on. 63 | 64 | Make your life easier by whitelisting your ssh key so you can login without a password 65 | 66 | 1. Copy the ssh key from your local machine to your clipboard, this differs per OS. 67 | 2. On your server, go into the `~/.ssh` folder (create it if it doesn't exist) 68 | 3. `nano authorized_keys` (this will create the file if it didn't exist yet) 69 | 4. Paste the key you copied in step 1. in this file 70 | 5. Exit the editor by pressing `ctrl + x` followed by `y` to save your changes 71 | 6. **Important**: keep your current commandline session open and try connecting to your server in a new screen. You should be able to login by simply typing `ssh @` and it should no longer prompt for a password. 72 | 73 | ### Useful aliases 74 | 75 | You can add aliases to your `~/.bashrc` file for commands you often run. In order to do this, simply run `nano ~/.bashrc` and add an alias. Afterwards, save and exit the file and enable the changes by running `source ~/.bashrc`, or by logging out and logging in to your server. 76 | 77 | ```bash 78 | alias pm2rl="pm2 restart all && pm2 logs" # Restart the core processes and open the logs afterward 79 | alias editpl="nano ~/.config/ark-core/mainnet/plugins.js" # Open the `plugins.js` file where you can find and add plugins 80 | alias editdel="nano ~/.config/ark-core/mainnet/delegates.json" # Open the `delegates.json` file where you can find your delegate passphrase 81 | alias cdsnaps="cd ~/.local/share/ark-core/mainnet/snapshots/" # Navigates to the snapshot folder 82 | ``` 83 | 84 | Note that the above location commands use `mainnet` by default. If you are on `devnet` or `testnet` instead, you need to replace `mainnet` with the network you use. 85 | 86 | ---- 87 | 88 | ## Security 89 | 90 | It's recommended that you setup additional security measurements for your node. Some options are explained in the [official ark docs](https://docs.ark.io/tutorials/node/secure.html), which include: 91 | 92 | * Changing SSH port and other config tweaks 93 | * Installing Fail2ban 94 | * Port Knocking 95 | * Cloudflare DDOS protection 96 | 97 | This is a good basis to have on your server, but you are free to look for other ways to secure it too. 98 | 99 | ---- 100 | 101 | ## Node Configuration 102 | 103 | ### Plugins / Scripts 104 | 105 | Some useful core plugins / scripts that you can install on your server: 106 | 107 | * [Vanir](https://github.com/ItsANameToo/vanir) - an easy way to self-forge your delegate payout transactions 108 | * [Hermod](https://github.com/ItsANameToo/hermod) - a monitoring and automatic snapshot tool to keep track of your server and to easily keep snapshots 109 | * [Core Control](https://github.com/geopsllc/core-control) - an alternative to the official ARK Cli, with additional features 110 | 111 | There are also a couple options for TBW scripts: 112 | 113 | * [Cryptology's TBW](https://github.com/wownmedia/cryptology_tbw) 114 | * [Ploutos](https://github.com/faustbrian/ploutos) 115 | * [Goose's TBW](https://github.com/galperins4/tbw) 116 | 117 | ### .env File 118 | 119 | You can find a `.env` file in `$HOME/.config/ark-core/$network/.env` in which you can make changes regarding the default core plugins. 120 | Alternatively, you can run `ark env:list` to show what is currently set in the `.env` file. 121 | 122 | The most interesting environment options will be highlighted here: 123 | 124 | * `CORE_LOG_LEVEL=`, you can change this to your preferred log level (e.g. `debug`, `info`, etc.). This can also be achieved through the CLI by running `ark env:set CORE_LOG_LEVEL ` 125 | * `CORE_DB_USERNAME=` and `CORE_DB_PASSWORD`, these values are used by core to log in to your local database. If you are having issues with accessing the database, you can change those entries as they default to user `ark` and password `password`, which might not be the actual values used on your server. 126 | 127 | ---- 128 | 129 | ## Snapshots 130 | 131 | It is recommended to keep a list of snapshots in case of issues with your node. As snapshots are no longer provided by the ARK team, it's your own responsibility to create and maintain them. You can easily keep a list of snapshots by installing [Hermod](https://github.com/ItsANameToo/hermod), or check below how you can create them manually. 132 | 133 | ### Creating a Snapshot 134 | 135 | A snapshot can be created with `ark snapshot:dump`. The full list of options can be found in the [official ARK snapshot docs](https://docs.ark.io/guidebook/core/cli.html#usage-26). In most cases, it will suffice to use the following command: 136 | 137 | ```bash 138 | ark snapshot:dump --network="mainnet" 139 | ``` 140 | 141 | ### Restoring from a Snapshot 142 | 143 | A snapshot can be restored with `ark snapshot:restore`. The full list of options can be found in the [official ARK snapshot docs](https://docs.ark.io/guidebook/core/cli.html#usage-27). In most cases, it will suffice to use the following command: 144 | 145 | ```bash 146 | ark snapshot:restore --network="mainnet" 147 | ``` 148 | 149 | ### Rollback 150 | 151 | In case your node gets stuck, it can in some cases suffice to rollback a couple blocks before the issue surfaced and let it sync with the network from there. This can be done with the following command: 152 | 153 | ```bash 154 | ark snapshot:rollback --network=NETWORK --height=HEIGHT 155 | ``` 156 | 157 | Here, `HEIGHT` is a number indicating the blockheight to which you want to roll back. If you want to go back to height `7.700.000` on `mainnet`, the command will look like this: 158 | 159 | ```bash 160 | ark snapshot:rollback --network="mainnet" --height=7700000 161 | ``` 162 | 163 | ### Database Dump 164 | 165 | You can also make a database dump instead of a snapshot. The following command will dump your `ark_mainnet` database to a file called `snapshot_latest`: 166 | 167 | ``` 168 | pg_dump -Fc ark_mainnet > snapshot_latest 169 | ``` 170 | 171 | To import the database dump, you need to run the following commands: 172 | 173 | ```bash 174 | dropdb ark_mainnet # or ark_devnet 175 | createdb ark_mainnet # or ark_devnet 176 | wget # fetch the snapshot, not needed if you already have it somewhere locally 177 | pg_restore -n public -O -j 8 -d ark_mainnet # where points to the location + name of the snapshot file 178 | ``` 179 | 180 | ### Sharing a Snapshot 181 | 182 | In case you need to share a snapshot between server (e.g. your forger was formatted and you want to get a snapshot from your relay), there is an easy method involving [Http Server](https://www.npmjs.com/package/http-server). 183 | 184 | 1. Install [Http Server](https://www.npmjs.com/package/http-server) on the server you have your snapshots on: `npm install http-server -g` 185 | 2. You can now serve any folder by running `http-server [path] [options]`. In case of snapshots, you can for example do the following: 186 | 187 | ```bash 188 | cdsnaps # Alias, otherwise use cd ~/.local/share/ark-core//snapshots/ 189 | http-server ./ 190 | ``` 191 | 3. Download your snapshot from another server through `wget` or something similar. 192 | 193 | Note: the default port used is `8080`, so if you have a firewall running you need to make sure that the port is open! 194 | 195 | Protip: you can make it easier to download a snapshot by tar'ing it, as that will combine the snapshot folder into a single file. 196 | 197 | ```bash 198 | cdsnaps 199 | # Combine a snapshot folder into a single file, make sure to rename mySnapshotFolder to the actual name of the snapshot folder 200 | tar cvf mySnapshotFolder.tar mySnapshotFolder 201 | ``` 202 | 203 | On the receiving server you can then extract the tar by running `tar -xvf mySnapshotFolder.tar` 204 | 205 | ---- 206 | 207 | ## Misc. 208 | 209 | ### Core File Locations 210 | 211 | Core v2 gets installed globally through `yarn` and can be found in the following location: 212 | 213 | ```bash 214 | ~/.config/yarn/global/node_modules/@arkecosystem/ 215 | ``` 216 | 217 | There are multiple locations that are used by core to store specific config or data: 218 | 219 | ```bash 220 | CORE_PATH_DATA=$HOME/.local/share/ark-core/$network 221 | CORE_PATH_CONFIG=$HOME/.config/ark-core/$network 222 | CORE_PATH_CACHE=$HOME/.cache/ark-core/$network 223 | CORE_PATH_LOG=$HOME/.local/state/ark-core/$network 224 | CORE_PATH_TEMP=/tmp/$USER/ark-core/$network 225 | 226 | cache => $HOME/.cache/ark-core/$network 227 | config => $HOME/.config/ark-core/$network 228 | database => $HOME/.local/share/ark-core/$network/database 229 | .env => $HOME/.config/ark-core/$network/.env 230 | logs => $HOME/.local/state/ark-core/$network/logs 231 | snapshots => $HOME/.local/share/ark-core/$network/snapshots 232 | temp => /tmp/$USER/ark-core/$network 233 | ``` 234 | 235 | In the above paths, `$network` needs to be replaced by `mainnet`, `devnet` or `testnet`, depending on which network you currently are 236 | 237 | ### Disabling API Ratelimit 238 | 239 | If you run into API Ratelimit issues on your node, you can disable it (or whitelist the IP that needs access). Disabling is done by adding `CORE_API_RATE_LIMIT=false` to your `.env` file. 240 | 241 | ### Whitelisting IPs 242 | 243 | You can limit access to the public api on your node by whitelisting IPs. 244 | By default, the whitelist consists of `*`, which means that everyone can access it. 245 | When you want to change it to just your server, you can remove the `*` and fill in the IP(s) that you allow. 246 | The whitelist can be found in the `~/.config/ark-core/mainnet/plugins.js` file, under `@arkecosystem/core-api`. 247 | Don't forget to restart your relay afterwards. 248 | 249 | ### Getting logs from server 250 | 251 | You can fetch logs from your remove server through `scp`. Note that you need to replace `$network` with `mainnet` or `devnet` 252 | 253 | Download the full log directory to your current directory: 254 | 255 | ```bash 256 | scp -r username@server:~/.local/state/ark-core/$network/ . 257 | ``` 258 | 259 | Download a single log file to your current directory 260 | 261 | ```bash 262 | scp username@server:~/.local/state/ark-core/$network/2019-03-11.log . # Change the filename to the correct date 263 | ``` 264 | 265 | If you use a different ssh port than the default `22`, you can run the above commands with `scp -P $port` instead, where `$port` is the port number you use. 266 | 267 | ---- 268 | 269 | ## Common Issues / FAQ 270 | 271 | ### Removing Processes from PM2 272 | 273 | You can remove a process from PM2 by running `pm2 delete ID` if you want to remove a specific process, or `pm2 delete all` if you want to remove everything. 274 | The ID of a process can be retrieved by running `pm2 list`, as it will show the ID next to the name of the process. 275 | If you don't see the ID, try increasing the size of your terminal window and running `pm2 list` again. 276 | 277 | ### Process Showing Errored 278 | 279 | When you try to start the relay / forger and you see `errored` when running `pm2 list`, it means that the process could not be started successfully. 280 | In that case, you should take a look at the logs (`pm2 logs`) as that should indicate why it was not able to start. 281 | 282 | ### Cannot find module ... 283 | 284 | If you run into an error indicating `Error: Cannot find module '...'`, it most likely means that you have a no longer supported plugin, or an incorrect plugin, added in your `plugins.js` file. 285 | The followup line in that case would be `at PluginRegistrar.__resolve`. 286 | To solve it, you simply have to edit your `plugins.js` file and remove / change the module it showed in the error message. 287 | 288 | If you see something else directly below the error, not related to the `PluginRegistrar`, it can also mean that a package is not correctly installed. 289 | 290 | ### The "..." process has entered an unknown state 291 | 292 | This often indicates an issue with PM2 itself. 293 | Most likely you'll be able to resolve it by running `pm2 update`. 294 | If it still gives the error after updating, run `pm2 kill` and start the processes again. 295 | 296 | ---- 297 | 298 | ## Useful Links 299 | 300 | * [ARK CLI Docs](https://docs.ark.io/guidebook/core/cli.html) 301 | * [Creating Plugins](https://docs.ark.io/guidebook/developer/write-a-plugin.html) 302 | * [ARK Core Docs](https://docs.ark.io/guidebook/core/) 303 | * [Migrating v2.1 to v2.2](https://docs.ark.io/releases/v2.2/migrating_2.1_2.2.html) 304 | * [Installing v2.2 from scratch](https://docs.ark.io/guidebook/core/cli.html#fresh-installation) 305 | * [VoteReport](https://explorer.ark.io/VoteReport.txt) 306 | 307 | --- 308 | 309 | ## Suggestions 310 | 311 | If you have any suggestions / improvements for this cheatsheet, feel free to open a PR or an issue to get it added! 312 | --------------------------------------------------------------------------------