Container File 💻 🔗 Geth

Configure and operate Geth (Go-Ethereum): an Ethereum blockchain client written in Go.

Overview

• Setup
  • Build
  • Config
• Operations
• Examples
• License
• Author Information

Setup

---

Guidelines on running 0labs/geth containers are available and organized according to the following software & machine provisioning stages:

• build
• config
• operations

Build

args

Name	description
build_version	base image to utilize for building application binaries/artifacts
geth_version	geth application version to build within image
goss_version	goss testing tool version to install within image test target
version	container/image infra application version

docker build --build-arg <arg>=<value> -t <tag> .

targets

Name	description
builder	image state following build of geth binary/artifacts
test	image containing test tools, functional test cases for validation and release target contents
release	minimal resultant image containing service binaries, entrypoints and helper scripts
tool	setup consisting of all geth utilities, helper tooling and release target contents

docker build --target <target> -t <tag> .

Config

📃 Configuration of the geth client can be expressed in a config file written in TOML, a minimal markup format, used as an alternative to passing command-line flags at runtime. To get an idea how the config should look you can use the geth dumpconfig subcommand to export a client's existing configuration. Also, a list of configurable settings can be found here.

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

$GETH_CONFIG_DIR=</path/to/configuration/dir> (default: /root/.ethereum/geth)

• container path where the geth TOML configuration should be maintained

  GETH_CONFIG_DIR=/mnt/etc/geth

$CONFIG-<section-keyword>-<section-property> = <property-value (string)> default: None

• Any configuration setting/value key-pair supported by geth should be expressible and properly rendered within the associated TOML config.

  <section-keyword> -- represents TOML config sections:

  # [TOML Section 'Shh']
  CONFIG-Shh-<section-property>=<property-value>

  <section-property> -- represents a specific TOML config section property to configure:

  # [TOML Section 'Shh']
  # Property: MaxMessageSize
  CONFIG-Shh-MaxMessageSize=<property-value>

  <property-value> -- represents property value to configure:

  # [TOML Section 'Shh']
  # Property: MaxMessageSize
  # Value: 2097152
  CONFIG-Shh-MaxMessageSize=2097152

Additionally, the content of the TOML configuration file can either be pregenerated and mounted into a container instance:

$ cat custom-config.toml
[Eth]
SyncMode = "light"

[Node]
DataDir = "/mnt/data/geth"

# mount custom config into container
$ docker run --env GETH_CONFIG_DIR=/tmp/geth --mount type=bind,source="$(pwd)"/custom-config.toml,target=/tmp/geth/config.toml 0labs/geth:latest

...or developed from both a mounted config and injected environment variables (with envvars taking precedence and overriding mounted config settings):

$ cat custom-config.toml
[Eth]
SyncMode = "light"

[Node]
DataDir = "/mnt/data/geth"

# mount custom config into container
$ docker run -it --env GETH_CONFIG_DIR=/tmp/geth --env CONFIG-Eth-SyncMode=full \
  --mount type=bind,source="$(pwd)"/custom-config.toml,target=/tmp/geth/config.toml \
  0labs/geth:latest

Moreover, see here for a list of supported flags to set as runtime command-line flags.

# connect to Ethereum mainnet and enable HTTP-RPC service 
docker run 0labs/geth:latest geth --mainnet --http

$EXTRA_ARGS=<string> (default: '')

• space separated list of command-line flags to pass at run-time

  docker run --env EXTRA_ARGS="--goerli --http --metrics" 0labs/geth:latest

...and reference below for network/chain identification and communication configs:

port mappings

Port	mapping description	type	config setting	command-line flag
8545	RPC server	TCP	Node : HTTPPort	--http.port
8546	Websocket RPC server	TCP	Node : WSPort	--ws.port
30303	protocol peer gossip and discovery	TCP/UDP	Node.P2P : ListenAddr	--port
6060	metrics collections	TCP	Metrics : Port	--metrics.port

chain id mappings

name	config setting (Eth : NetworkId)	command-line flag
Mainnet	1	--mainnet
Goerli	5	--goerli
Kovan	42	n/a
Rinkeby	4	--rinkeby
Ropsten	3	--ropsten

see chainlist.org for a complete list

Operations

🔦 To assist with managing a geth client and interfacing with the Ethereum network, the following utility functions have been included within the image. Note: all tool command-line flags can alternatively be expressed as container runtime environment variables, as described below.

Check account balances

Display account balances of all accounts currently managed by a designated geth RPC server.

$ geth-helper status check-balances --help
Usage: geth-helper status check-balances [OPTIONS]

  Check all client managed account balances

Options:
  --rpc-addr TEXT  server address to query for RPC calls  [default:
                   (http://localhost:8545)]
  --help           Show this message and exit.

$RPC_ADDRESS=<web-address> (default: localhost:8545)

• geth RPC server address for querying network state

The balances output consists of a JSON list of entries with the following properties:

• account - account owner's address
• balance - total balance of account in decimal

example

docker exec --env RPC_ADDRESS=geth-rpc.live.01labs.net 0labs/geth:latest geth-helper status check-balances

[
  {
   "account": 0x652eD9d222eeA1Ad843efab01E60C29bF2CF6E4c,
   "balance": 1000000
  },
  {
   "account": 0x256eDb444eeA1Ad876efaa160E60C29bF8CH3D9a,
   "balance": 2000000
  }
]

View client sync progress

View current progress of an RPC server's sync with the network if not already caughtup.

$ geth-helper status sync-progress --help
Usage: geth-helper status sync-progress [OPTIONS]

  Check client blockchain sync status and process

Options:
  --rpc-addr TEXT  server address to query for RPC calls  [default:
                   (http://localhost:8545)]
  --help           Show this message and exit.

$RPC_ADDRESS=<web-address> (default: localhost:8545)

• geth RPC server address for querying network state

The progress output consists of a JSON block with the following properties:

• progress - percent (%) of total blocks processed and synced by the server
• blocksToGo - number of blocks left to process/sync
• bps: rate of blocks processed/synced per second
• percentageIncrease - progress percentage increase since last view
• etaHours - estimated time (hours) to complete sync

example

$ docker exec 0labs/geth:latest geth-helper status sync-progress

  {
   "progress":66.8226399830796,
   "blocksToGo":4298054,
   "bps":5.943412173361741,
   "percentageIncrease":0.0018371597201962686,
   "etaHours":200.87852803477827
  }

Backup and encrypt keystore

Encrypt and backup client keystore to designated container/host location.

$ geth-helper account backup-keystore --help
Usage: geth-helper account backup-keystore [OPTIONS] PASSWORD

  Encrypt and backup wallet keystores.

  PASSWORD password used to encrypt and secure keystore backups

Options:
  --keystore-dir TEXT  path to import a backed-up geth wallet key store
                       [default: (/root/.ethereum/keystore)]
  --backup-path TEXT   path containing backup of a geth wallet key store
                       [default: (/tmp/backups)]
  --help               Show this message and exit.

$BACKUP_PASSWORD=<string> (required)

• password used to encrypt and secure keystore backups. Keystore backup is encrypted using the zip utility's password protection feature.

$KEYSTORE_DIR=<string> (default: /root/.ethereum/keystore)

• container location to retrieve keys from

$BACKUP_PATH=<string> (default: /tmp/backups)

• container location to store encrypted keystore backups. Note: Using container volume/mounts, keystores can be backed-up to all kinds of storage solutions (e.g. USB drives or auto-synced Google Drive folders)

$AUTO_BACKUP_KEYSTORE=<boolean> (default: false)

• automatically backup keystore to $BACKUP_PATH location every $BACKUP_INTERVAL seconds

$BACKUP_INTERVAL=<cron-schedule> (default: 0 * * * * (hourly))

• keystore backup frequency based on cron schedules

Import backup

Decrypt and import backed-up keystore to designated container/host keystore location.

$ geth-helper account import-backup --help
Usage: geth-helper account import-backup [OPTIONS] PASSWORD

  Decrypt and import wallet keystores backups.

  PASSWORD password used to decrypt and import keystore backups

Options:
  --keystore-dir TEXT  directory to import a backed-up geth wallet key store
                       [default: (/root/.ethereum/keystore)]
  --backup-path TEXT   path containing backup of a geth wallet key store
                       [default: (/tmp/backups/wallet-backup.zip)]
  --help               Show this message and exit.

$password=<string> (required)

• password used to decrypt keystore backups. Keystore backup is decrypted using the zip/unzip utility's password protection feature.

$KEYSTORE_DIR=<string> (default: /root/.ethereum/keystore)

• container location to import keys

$BACKUP_PATH=<string> (default: /tmp/backups)

• container location to retrieve keystore backup. Note: Using container volume/mounts, keystores can be imported from all kinds of storage solutions (e.g. USB drives or auto-synced Google Drive folders)

Query RPC

Execute query against designated geth RPC server.

$ geth-helper status query-rpc --help
Usage: geth-helper status query-rpc [OPTIONS]

  Execute RPC query

Options:
  --rpc-addr TEXT  server address to query for RPC calls  [default:
                   (http://localhost:8545)]
  --method TEXT    RPC method to execute a part of query  [default:
                   (eth_syncing)]
  --params TEXT    comma separated list of RPC query parameters  [default: ()]
  --help           Show this message and exit.

$RPC_ADDRESS=<web-address> (default: localhost:8545)

• geth RPC server address for querying network state

$RPC_METHOD=<geth-rpc-method> (default: eth_syncing)

• geth RPC method to execute

$RPC_PARAMS=<rpc-method-params> (default: '')

• geth RPC method parameters to include within call

The output consists of a JSON blob corresponding to the expected return object for a given RPC method. Reference Ethereum's RPC API wiki for more details.

example

docker exec --env RPC_ADDRESS=geth-rpc.live.01labs.net --env RPC_METHOD=eth_gasPrice \
    0labs/geth:latest geth-helper status query-rpc

"0xe0d7b70f7" # 60,355,735,799 wei

Examples

• Create account and bind data/keystore directory to host path (note: automatic loading of config should be disabled):

docker run --env NOLOAD_CONFIG=1 -it -v /mnt/geth/data:/root/.ethereum/ 0labs/geth:latest geth account new --password <secret>

• Launch an Ethereum light client and connect it to the Ropsten, best current like-for-like representation of Ethereum, PoW (Proof of Work) test network:

docker run --env CONFIG-Eth-SyncMode=light --EXTRA_ARGS="--ropsten" 0labs/geth:latest

• View sync progress of active local full-node:

docker run --name 01-geth --detach --env CONFIG-Eth-SyncMode=full --env EXTRA_ARGS="--mainnet" 0labs/geth:latest

docker exec 01-geth geth-helper status sync-progress

• Run light sync node with automatic daily backups of custom keystore directory:

docker run --env CONFIG-Eth-SyncMode=light --env KEYSTORE_DIR=/tmp/keystore \
           --env AUTO_BACKUP_KEYSTORE=true --env BACKUP_INTERVAL="0 * * * *" \
           --env BACKUP_PASSWORD=<secret> \
  --volume ~/.ethereum/keystore:/tmp/keystore 0labs/geth:latest

• Import account from keystore backup stored on an attached USB drive:

docker run --name 01-geth --detach --env CONFIG-Eth-SyncMode=full --env EXTRA_ARGS="--mainnet" \
           --volume /path/to/usb/mount/keys:/tmp/keys \
           --volume ~/.ethereum:/root/.ethereum \0labs/geth:latest

docker exec --env BACKUP_PASSWORD=<secret>
            --env BACKUP_PATH=/tmp/keys/my-wallets.zip
            01-geth geth-helper account import-backup

docker exec 01-geth account import /root/.ethereum/keystore/a-wallet

• Initialize client genesis block and definition and run node on Kintsugi testnet:

docker run --env GETH_CONFIG_DIR=/tmp/geth --env GENESIS_INIT_PATH=https://raw.githubusercontent.com/parithosh/consensus-deployment-ansible/master/kintsugi-testnet/custom_config_data/genesis.json --env CONFIG-Eth-NetworkId=1337702 --env EXTRA_ARGS="--catalyst" 0labs/geth:latest 

License

MIT

Author Information

This Containerfile was created in 2021 by O1.IO.

🏆 always happy to help & donations are always welcome 💸

• ETH (Ethereum): 0x652eD9d222eeA1Ad843efec01E60C29bF2CF6E4c

• BTC (Bitcoin): 3E8gMxwEnfAAWbvjoPVqSz6DvPfwQ1q8Jn

• ATOM (Cosmos): cosmos19vmcf5t68w6ug45mrwjyauh4ey99u9htrgqv09