IDENA Sibling

Ansible Playbook for fast Idena Shared Node Deployment and management.

💬 Overview

The main goal of this playbook is to facilitate a quick and secure deployment of Idena Node / Shared Node. You can configure all parameters of your node / shared node and easily update your shared node API keys. If you choose to deploy a shared node, it will be deployed using an HTTPS connection. You can opt to use your own SSL certificate or a certificate from Let's Encrypt. If you choose to use Let's Encrypt, the certificate will be automatically updated via a special crontab task.

📚 The complete guide of how to use Idena Sibling is available here:

https://medium.com/@idna.project/6ff31873101b

🫴 Requirements:

Destination droplets:

Python version 3.9 or higher is required.
Your public SSH key must be added to the authorized_keys file on the server. You can use the following command: ssh-copy-id -i ~/.ssh/mykey user@host . Alternatively, you may use password authentication as a less secure option. To change the authentication method, please modify the value of the sshd_PasswordAuthentication variable inside the ./group_vars/main/vars file and uncomment the ansible_connection variable inside the host file located in the root of the repository folder.
The script has been tested on Ubuntu 20.04 LTS and may work on other Debian-based distributions, but they have not been explicitly tested.

Master node:

Python version 3.9 or higher and pip3 must be installed.
The latest version of Ansible must be installed on the machine.
If you are using a Windows machine, you can run this playbook by using WSL2 with an Ubuntu distribution.

⚙️ Configuration

🔐 Secret and Public vars:

Secret (vault file) and public (vars file) variables are stored in the ./idena-sibling/group_vars/main/ folder.
api_keys.yaml and api_mgmt.yaml consist of variables that are responsible for managing your API keys.

✧ The file api_keys.yaml contains the complete list of your API keys that need to be added to your shared node during the deployment process using the idena_shared.yaml playbook;
✦ The file api_mgmt.yaml contains two variables with keys that are meant to be added or removed after the installation of the shared node. This can be achieved using the idena_node_mgmt.yaml playbook with the tag IdenaApiKeysUpdate.

Please note: that the Shared Node Installation playbook (idena_shared.yaml) will import API keys from the api_keys.yaml file and ignore the values from the api_mgmt.yaml file, such as api_keys_add and api_keys_remove.

On the other hand, the Idena Node Management playbook (idena_node_mgmt.yaml) will use api_keys_add and api_keys_remove variables from the ./idena-sibling/group_vars/main/api_mgmt.yaml file to add and remove keys on your shared node idena-node-proxy configuration:

✵ It will add new keys, remove old ones, and delete duplicates. After all of these manipulations, the apiKeys values will be synced with your local ./idena-sibling/group_vars/main/api_keys.yaml file.

So, you would always have a fresh and synchronized copy of your droplet API keys.

Sensitive variables are stored in a special secret vault file, which is saved as an encrypted file (./idena-sibling/group_vars/main/vault).
To edit this file, you must remove the existing one and create a new file with your own password using the command ansible-vault create vault. To edit this file in the future, use the command ansible-vault edit vault. The file must have a similar structure to the example provided below:

---
vault_api_key: "your shared node api key"
vault_node_key: "your shared node pure private key"
userpass: "the password of the user under which name your shared node gonna be run"
letsencrypt_email: "email@for_letsencrypt_certificate.com"
droplet_domain: "your.droplet_domain.com"
#ansible_ssh_pass: "your_droplet_ssh_sudo_pass"
#ansible_sudo_pass: "your_droplet_sudo_pass"

To avoid having to re-enter your vault storage password every time you want to edit it, please save it in the .vault_pass plain text file in the root folder of the repository.

📜 Generating a PEM file for your SSL certificate:

If you have your own SSL certificate for your shared node domain please check that the value of letsencrypt variable is set to no. Generally, after purchasing an SSL certificate, you will receive a file archive containing the following files.

.crt
server.csr
server.key

To generate a Privacy Enhanced Mail (PEM) file, you typically need to concatenate the two files using the following command inside the folder that contains the crt and key files:
cat server.crt server.key > domain_pem

After creating your final PEM file called domain_pem, you would need to copy it (overwrite the existed one) to the ./idena-sibling/node/ folder of the repository and encrypt it using the command ansible-vault encrypt domain_pem.
If you want to change the contents of your certificate vault storage in the future, you can use the command ansible-vault edit domain_pem.

📜 Generate and Install a Let's Encrypt SSL Certificate:

Apart from using your own SSL certificate, the certificate can be issued by the Let's Encrypt provider by setting the value of the letsencrypt variable to yes. In that case, please ensure that the A record of your shared node domain has been correctly set to the IP address of the droplet that you are using to install your shared node. If everything has been set correctly, you will end up with a fully configured shared node, including a special crontask to automatically update your Let's Encrypt SSL certificate before it expires.

📢 Public Variables Configuration

The playbook has been configured to change all parameters from configuration files of idena-go and idena-node-proxy applications. You could have a look at idena-sibling/group_vars/main/vars file. Hovewer I will put your attention on the most important variables that with great probability you would like to change:

In case if you don't want to download the bootstrap idenachain.db archive you would have to set idenachain_bootstrap variable to no.
The public variable idena_go_ver supports not only version numbers like 1.0.4 but also the value latest, which means that the latest version of the Idena-go node client will be downloaded.
sshd_PasswordAuthentication: "no" By setting this variable, you can choose to use or avoid using an SSH password to authenticate to your server. Please be careful when setting the value to no, as if you lose your private key, you won't be able to authenticate yourself in the droplet.
letsencrypt: "yes" Choosing between Let's Encrypt SSL Certificate and your own SSL certificate that would be imported from ./node/domain_pem file.

🎯 Hosts configuration

All variables related to the destination connection must be set in the main hosts file, which is available in the root folder of the repository and is named hosts.

[main]
XXX.YYY.ZZZ.UUU

[all:vars]
ansible_ssh_private_key_file = ~/.ssh/id_rsa
ansible_user = root
idena_group = Olga
username = Olga
public_key_file = ~/.ssh/id_rsa.pub
#ansible_connection=ssh
#ansible_ssh_port=10222

If you prefer to use root password authentication instead of SSH key authentication, you will need to set your root password in the vault data storage under ansible_ssh_pass variable as described earlier and uncomment ansible_connection=ssh variable in the hosts file.

#ansible_ssh_port=10222 - if you are using a non-standard SSH port, you would need to uncomment and set it here.

⏳ Install required collections and python libraries on your local machine:

Before starting to use these playbooks, please install the required Python packages and Ansible-galaxy modules.

Installing dnspython library pip3 install dnspython
Installing required ansible community modules ansible-galaxy install -r requirements.yml

🚀 Run the playbook:

If the host_key_checking variable from ansible.cfg file is set to false, use ssh-copy-id root@XXX.YYY.ZZZ.UUU to automatically copy your public SSH key to the authorized_keys file on your destination droplet server.

☑ After setting all parameters, run the playbook depends on what kind of installation you would like to make:

Regular node installation: ansible-playbook -i hosts idena_node.yaml
Shared node installation: ansible-playbook -i hosts idena_shared.yaml
Management of Idena Node after installation: ansible-playbook -i hosts idena_node_mgmt.yaml --tags operation_tag_name

Possible values of operation_tag_name:

IdenaNodekeyUpdate: Takes a new nodekey (private key) value from the vault_node_key variable.
IdenaNodeStart: Starts the Idena Node.
IdenaNodeStop: Stops the Idena Node.
IdenaMiningOn: Changes mining status to ON.
IdenaMiningOff: Changes mining status to OFF.
IdenaApiKeysUpdate: Updates Shared Node API keys after chaning values inside ./group_vars/main/api_keys.yaml and ./group_vars/main/api_mgmt.yaml.
IdenaGoUpdate: Updates your idena-go node client to the version specified in the idena_go_ver variable. If idena_go_ver is set to latest, it will upgrade the idena-go node client to the latest version.
IdenaProxyUpdate: Updates your idena-node-proxy to the latest version.
IdenaChainRefresh: Initiates a complete resync of the Idena blockchain.
IPFSRefresh: Initiates a complete resync of the IPFS.

🗒️ Ater using the playbook there are a few things left to do:

✦ If you have used a custom SSL certificate option (letsencrypt: "no") and haven't done so already, change the DNS A record related to your droplet domain.
✧ Try accessing your shared node's domain via a web browser using the "https://" prefix.
✧ Try to connect to your shared node using any of your API keys via app.idena.io.
✦ Please remember that after entering the API key and Shared Node URL in the app.idena.io, your status should become 'ONLINE'.

──────────────────────────────────────────────────
💻 LTraveler:
💬 Telegram: https://t.me/ltrvlr
🌐 WWW: https://ltraveler.github.io
👛 0xf041640788910fc89a211cd5bcbf518f4f14d831

Please note: All playbooks inside this repository have been tested on the author's own droplets. There's no warranty, one should use it at one's own risk.

ltraveler/idena-sibling