Giters

edsburke / ansible-role-lotus

Install and configure Lotus, an implementation of the Filecoin distributed storage network protocol written in Go

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

ansible logo

lotus logo

Ansible Role 🌸 🔗 Lotus

Galaxy Role GitHub release (latest by date) Downloads Build Status License: MIT

Table of Contents

Ansible role that installs and configures Lotus: a Go-implementation of the Filecoin distributed storage network blockchain protocol.

Supported Platforms:
* Debian
* Redhat(CentOS/Fedora)
* Ubuntu

Requirements

Requires the unzip/gtar utility to be installed on the target host. See ansible unarchive module notes for details.

Role Variables

Variables are available and organized according to the following software & machine provisioning stages:

  • install
  • config
  • launch
  • uninstall

Install

lotuscan be installed using compressed archives (.tar, .zip), downloaded and extracted from various sources, or built from git source.

The following variables can be customized to control various aspects of this installation process, ranging from software version and source location of binaries to the installation directory where they are stored:

lotus_user: <service-user-name> (default: lotus)

  • dedicated service user and group used by lotus for privilege separation (see here for details)

install_type: <archive | source> (default: archive)

  • archive: currently supported by Ubuntu and Fedora distributions (due to availibity of version >= 2.27 of the glibc GNU libc libraries package -- see here for per-distribution package availability) and compatible with both tar and zip formats, installation of Lotus via compressed archives results in the direct download of its component binaries, the lotus network client and lotus-storage-miner mining software, from the specified archive url.

    note: archived installation binaries can be obtained from the official releases site or those generated from development/custom sources.

  • source: build lotus network client and storage miner binaries from source. This installation process consists of cloning the github hosted repository and building from source code using make directives. See here for more details on building from source.

install_dir: </path/to/installation/dir> (default: /opt/lotus)

  • path on target host where the lotus binaries should be extracted to.

archive_url: <path-or-url-to-archive> (default: see defaults/main.yml)

  • address of a compressed tar or zip archive containing lotus binaries. This method technically supports installation of any available version of lotus. Links to official versions can be found here.

archive_checksum: <path-or-url-to-checksum> (default: see defaults/main.yml)

  • address of a checksum file for verifying the data integrity of the specified archive. While recommended and generally considered a best practice, specifying a checksum is not required and can be disabled by providing an empty string ('') for its value.

checksum_format: <string> (default: see sha512)

  • hash algorithm used for file verification associated with the specified archive or package checksum. Reference here for more information about checksums/cryptographic hashes.

git_url: <path-or-url-to-git-repo> (default: see defaults/main.yml)

  • address of lotus git repository. Address can reference the Github site address or custom source hosted on an alternate git hosting site.

git_version: <string> (default: v0.1.0)

  • version of the repository to check out. This can be the literal string HEAD, a branch name, a tag name.

lotus_path: </path/to/runtime/dir> (default: /opt/lotus/.lotus)

  • path on target host the lotus service should establish as its runtime configuration and data directory.

lotus_storage_path: </path/to/miner/data-dir> (default: /opt/lotus/.lotusstorage)

  • path on target host the lotus-storage-miner service should establish as its runtime and data storage directory.

go_autoinstall: <true|false> (default: false)

  • automatically install the specified version of Go packages and binaries. Useful when installing from source which requires go as a part of its build process

go_url: <path-or-url-to-archive> (default: see defaults/main.yml)

  • address of a compressed tar or zip archive containing go binaries or source for compilation. This method technically supports installation of any available version of go. Links to official versions can be found here.

go_install_dir: </path/to/install/dir> (default: /usr/local)

  • path on target host where the go binaries should be extracted to.

Config

Configuration of the lotus client can be expressed in a config file written in TOML, a minimal markup language. Note: This file can be found under the directory specified by the LOTUS_PATH (for the lotus client/service) or LOTUS_STORAGE_PATH (for the lotus miner) environment variables. For an idea of the available configuration options, reference this example (installed by default).

The following variables can be customized to manage the content of this TOML configuration:

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

  • Any configuration setting/value key-pair supported by lotus should be expressible within the config hash and properly rendered within the associated TOML config. Values can be expressed in typical yaml/ansible form (e.g. Strings, numbers and true/false values should be written as is and without quotes).

    Furthermore, configuration is not constrained by hardcoded author defined defaults or limited by pre-baked templating. If the config section, setting and value are recognized by the lotus tool, 👍 to define within config.

    Keys of the config hash represent TOML config sections:

    config:
  # [TOML Section 'API']
  API: {}

    Values of config[<key>] represent key,value pairs within an embedded hash expressing config settings:

    config:
  # TOML Section '[API]'
  API:
    # Section setting ListenAddress with value of localhost binding at port 1234
    ListenAddress: "/ip4/127.0.0.1/tcp/1234/http"

Launch

Running the lotus distributed storage network protocol service/API server in addition to the lotus-storage-miner storage miner agent is accomplished utilizing the systemd service management tool for both archive and source installations. Launched as background processes or daemons subject to the configuration and execution potential provided by the underlying management framework, launch of either service can be set to adhere to system administrative policies right for your environment and organization.

The following variables can be customized to manage the services' systemd [Service] unit definition and execution profile/policy:

extra_run_args: <lotus-cli-options> (default: [])

  • list of lotus daemon commandline arguments to pass to the binary at runtime for customizing launch. Supporting full expression of lotus daemon's cli, this variable enables the launch to be customized according to the user's specification.

extra_miner_args: <lotus-storage-miner-cli-options> (default: [])

  • list of lotus-storage-miner run commandline arguments to pass to the binary at runtime for customizing launch. Supporting full expression of lotus-storage-miner run's cli, this variable enables the launch to be customized according to the user's specification.

custom_unit_properties: <hash-of-systemd-service-settings> (default: [])

  • hash of settings used to customize the [Service] unit configuration and execution environment of the Lotus systemd service.

custom_miner_properties: <hash-of-systemd-service-settings> (default: [])

  • hash of settings used to customize the [Service] unit configuration and execution environment of the Lotus Storage Miner systemd service.
Example
custom_unit_properties:
  Environment: "LOTUS_PATH=/var/data/lotus"
custom_miner_properties:
  Environment: "LOTUS_STORAGE_PATH=/var/data/lotus-storage-miner"

Reference the systemd.service man page for a configuration overview and reference.

Uninstall

Support for uninstalling and removing artifacts necessary for provisioning allows for users/operators to return a target host to its configured state prior to application of this role. This can be useful for recycling nodes and roles and perhaps providing more graceful/managed transitions between tooling upgrades.

The following variable(s) can be customized to manage this uninstall process:

perform_uninstall: <true | false> (default: false)

  • whether to uninstall and remove all artifacts and remnants of this lotus installation on a target host (see: handlers/main.yml for details)

Dependencies

  • 0x0i.systemd

Example Playbook

default example:

- hosts: all
  roles:
  - role: 0x0I.lotus

install lotus from specified git source version:

- hosts: all
  roles:
  - role: 0x0I.lotus
    vars:
      install_type: source
      git_url: https://github.com/filecoin-project/lotus.git
      git_version: v0.1.1

expose lotus API/JSON-RPC server on non-loopback (wildcard/*) address

- hosts: all
  roles:
  - role: 0x0I.lotus
    vars:
      install_type: archive
      config:
        API:
          ListenAddress: /ip4/0.0.0.0/tcp/1234/http
        LibP2P:
          ListenAddresses: ["/ip4/0.0.0.0/tcp/0", "/ip6/::/tcp/0"]

launch lotus service and lotus-storage-miner agents with custom runtime/storage paths and launch options:

- hosts: all
  roles:
  - role: 0x0I.lotus
    vars:
      install_type: source
      lotus_path: /mnt/lotus
      lotus_storage_path: /mnt/lotus/miner
      config:
        Metrics:
          Nickname: "my_miner"
      extra_run_args: ['--bootstrap']
      extra_miner_args: ['--nosync']
      custom_miner_properties:
        LimitDATA: 1T

License

MIT

Author Information

This role was created in 2019 by O1.IO.

About

Install and configure Lotus, an implementation of the Filecoin distributed storage network protocol written in Go

Languages

Language:Ruby 97.5%Language:HTML 2.5%