<p><img src="https://code.benco.io/icon-collection/logos/ansible.svg" alt="ansible logo" title="ansible" align="left" height="60" /></p>
<p><img src="https://www.logo.wine/a/logo/Ethereum/Ethereum-Icon-Purple-Logo.wine.svg" alt="ethereum logo" title="ethereum" align="right" height="120" /></p>

Ansible Role :computer: :link: Geth
=========
[![Galaxy Role](https://img.shields.io/ansible/role/d/0x0i/geth)](https://galaxy.ansible.com/0x0I/geth)
![GitHub release (latest by date)](https://img.shields.io/github/v/release/0x0I/ansible-role-geth?color=yellow)
[![License: MIT](https://img.shields.io/badge/License-MIT-blueviolet.svg)](https://opensource.org/licenses/MIT)

**Overview**
- [Supported Platforms](#supported-platforms)
- [Requirements](#requirements)
- [Role Variables](#role-variables)
  - [Install](#install)
  - [Config](#config)
  - [Launch](#launch)
  - [Uninstall](#uninstall)
- [Dependencies](#dependencies)
- [Example Playbook](#example-playbook)
- [License](#license)
- [Author Information](#author-information)

This Ansible role installs, sets up, and runs [Geth](https://geth.ethereum.org/), which is a command-line tool and API for running an Ethereum node.

##### Supported Platforms:

• Debian
• MacOS
• Redhat (CentOS/Fedora)
• Ubuntu

Requirements
------------

You need to have the `unzip/gtar` utility installed on the target machine. For more details, check the ansible `unarchive` module [here](https://docs.ansible.com/ansible/latest/modules/unarchive_module.html#notes).

Role Variables
--------------
Variables are organized by different stages of software installation and machine provisioning:
* _install_
* _config_
* _launch_
* _uninstall_

#### Install

You can install `geth` using the operating system's package management tools (like `apt`, `homebrew`) or by downloading and extracting zipped or tarred files from various sources.

_The following variables let you control different parts of the installation, like software version, source location, and installation directory:_

`geth_user: <service-user-name>` (**default**: *geth*)
- A dedicated service user and group for `geth` to enhance security (more info [here](https://www.beyondtrust.com/blog/entry/how-separation-privilege-improves-security)).

`install_type: <package | archive>` (**default**: archive)
- **package**: Only available for Ubuntu and MacOS; this method installs the latest package from Ubuntu or Mac's repositories.
- **archive**: Works with both *tar and zip* formats, allowing installation from any available compressed file.

`archive_url: <path-or-url-to-archive>` (**default**: see `defaults/main.yml`)
- The location of a compressed **tar or zip** file containing `geth`.

`install_dir: </path/to/installation/dir>` (**default**: see `defaults/main.yml | vars/...`)
- The directory on the target machine where the `geth` binaries will be extracted.

#### Config

You can write the `geth` client configuration in a file using the TOML format, which is a simple markup language. You can export an existing configuration using the `geth dumpconfig` command.

_Customizable variables for the configuration include:_

`config_dir: </path/to/configuration/dir>` (**default**: `/etc/geth`)
- The directory where the `geth` configuration file will be stored.

`geth_config: {"<config-section>": {"<section-setting>": "<setting-value>",..},..}` **default**: see `defaults/main.yml`

* You can set any configuration that `geth` supports within the `geth_config`. 

  For examples on how to structure this, refer to the TOML sections in the variable above.

#### Launch

You can run the `geth` client and API server using system management tools like [systemd](https://www.freedesktop.org/wiki/Software/systemd/) for Linux and [launchd](https://www.launchd.info/) for MacOS. 

_Customizable variables for running `geth` include:_

`extra_run_args: <geth-cli-options>` (**default**: see `defaults/main.yml`)
- Command-line options for `geth`, allowing you to customize how it runs.

For example, you can connect to Ethereum test networks or enhance logging.

##### Examples

To connect to different Ethereum test networks:

extra_run_args:

• '--ropsten' # PoW

...or...

extra_run_args:

• '--rinkeby' # PoA

To enhance logging and debugging:

extra_run_args:

• --debug
• '--verbosity 5'
• '--trace /tmp/geth.trace'

To enable profiling for testing:

extra_run_args:

• --pprof
• '--memprofilerate 1048576'
• '--blockprofilerate 1'
• '--cpuprofile /tmp/geth-cpu-profile'

`custom_unit_properties: <hash-of-systemd-service-settings>` (**default**: `[]`)
- Settings to customize the configuration of the Geth service in `systemd`.

#### Uninstall

You can also uninstall `geth` and remove any related files, bringing the machine back to its previous state. This is helpful for reusing nodes.

_Customizable uninstallation variables:_

`perform_uninstall: <true | false>` (**default**: `false`)
- Whether to remove all aspects of the `geth` installation on the target machine (see `handlers/main.yml` for more).

Dependencies
------------

- 0x0i.systemd

Example Playbook
----------------
Basic setup:

• hosts: all roles:
  • role: 0x0I.geth

Launch an Ethereum light client connected to the Rinkeby test network:

• hosts: light-client roles:
  • role: 0x0I.geth vars: geth_config: Eth: SyncMode: light extra_run_args: - --rinkeby

Run a full Ethereum node with "fast" sync mode:

• hosts: full-node roles:
  • role: 0x0I.geth vars: geth_config: Eth: SyncMode: fast Node: DataDir: /mnt/geth extra_run_args: - --rpc - --nousb - '--rpcaddr="12.34.56.789"' - '--mine --miner.threads 16'

License
-------

MIT

Author Information
------------------

This role was created in 2019 by O1.IO.