Ansible Role: Cherry Blossom - Lotus

Table of Contents

• Supported Platforms
• Requirements
• Role Variables
  • Install
  • Config
  • Launch
  • Uninstall
• Dependencies
• Example Playbook
• License
• Author Information

This Ansible role installs and sets up Lotus, which is a Go implementation of the Filecoin blockchain protocol for distributed storage.

Supported Platforms:

* Debian
* Redhat (CentOS/Fedora)
* Ubuntu

Requirements

You need to have the unzip/gtar utility installed on the target host. For details, refer to the notes on the ansible unarchive module here.

Role Variables

Variables are organized based on various stages of software and machine setup:

• install
• config
• launch
• uninstall

Install

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

• This is the dedicated service user and group for running lotus, allowing for better security (learn more here).

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

• archive: For Ubuntu and Fedora, this downloads Lotus binaries directly from compressed archives.
• source: This downloads the source code from GitHub and builds it. More details can be found here.

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

• The directory on the target host where Lotus binaries will be extracted.

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

• Whether to build and install lotus-bench. More information can be found here.

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

• The URL of a compressed archive containing Lotus binaries. Official versions are found here.

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

• The URL for a checksum file used to verify the integrity of the archive. Specifying this is recommended but not mandatory.

checksum_format: <string> (default: see sha512)

• The type of hash to use for verifying the archive or package checksum. More information on checksums is here.

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

• The URL of the Lotus git repository on GitHub or another hosting platform.

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

• The version of the repository to check out.

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

• The runtime configuration and data directory for the lotus service.

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

• The runtime and data storage directory for the lotus-miner service.

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

• Whether to automatically install the specified version of Go packages.

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

• The URL of a compressed archive containing Go binaries or source code.

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

• Path on the target host for extracting Go binaries.

Config

The configuration for the lotus client is specified in a config file in TOML format.

You can customize these variables for the TOML configuration:

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

• The config hash can hold key-value pairs for any setting recognized by lotus.

Launch

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

• Additional command line arguments for lotus daemon.

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

• Additional command line arguments for lotus-miner run.

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

• Custom settings for the systemd service of the Lotus service.

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

• Custom settings for the systemd service of the Lotus Storage Miner.

Uninstall

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

• Whether to uninstall and remove all traces of the Lotus installation on the target host.

Dependencies

• 0x0i.systemd

Example Playbook

Default example:

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

To install lotus from a specific 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

To install lotus for the calibration network and include additional options:

- hosts: all
  roles:
    - ansible-rustup

- hosts: all
  environment:
    RUSTFLAGS: "-C target-cpu=native -g"
    FFI_BUILD_FROM_SOURCE: 1
  vars:
    cargo_home: "{{ /home/{{ ansible_env.HOME }}/.cargo }}"
  roles:
    - role: 0x0I.lotus
      vars:
        install_type: source
        include_benchmarks: true
        git_url: https://github.com/filecoin-project/lotus.git
        git_version: ntwk-calibration
        go_autoinstall: true
        go_url: https://dl.google.com/go/go1.15.5.linux-amd64.tar.gz

To expose the lotus API server:

- 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"]

To launch the lotus service with custom paths and options:

- hosts: all
  roles:
  - role: 0x0I.lotus
    vars:
      install_type: source
      lotus_path: /mnt/lotus
      lotus_storage_path: /mnt/lotus/miner
      managed_services: ['lotus', '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.