compose

package
v0.13.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 15, 2023 License: GPL-3.0 Imports: 23 Imported by: 0

README

Charon Compose

Run, test, and debug a developer-focussed insecure local charon cluster using docker-compose

Compose is a tool that generates docker-compose.yml files such that different charon clusters can be created and run.

The aim is for developers to be able to debug features and check functionality of clusters on their local machines.

The compose command should be executed in sequential steps:

  1. compose new: Creates a new config.json that defines what will be composed.
  2. compose define: Creates a docker-compose.yml that executes charon create dkg if keygen==dkg.
  3. compose lock: Creates a docker-compose.yml that executes charon create cluster or charon dkg.
  4. compose run: Creates a docker-compose.yml that executes charon run.

The compose command also includes some convenience functions.

  • compose clean: Cleans the compose directory of existing files.
  • compose auto: Runs compose define && compose lock && compose run.

Note that compose automatically runs docker-compose up at the end of each command. This can be disabled via --up=false.

The compose new step configures the target cluster and key generation process. See compose new --help for supported flags.

Usage Examples

Install the compose binary:

# From inside the charon repo
go install github.com/obolnetwork/charon/testutil/compose/compose

# Ensure that `.../go/bin` is in your path via `which compose`

# Alternatives:
# go install ./...
# cd testutil/compose/compose && go installl .
# cd testutil/compose/compose && go build -o /tmp/compose/compose

Create a charon compose workspace folder:

cd /tmp
mkdir charon-compose
cd charon-compose

Create the default cluster:

compose clean && compose new && compose define && compose lock && compose run

Monitor the cluster via grafana and jaeger:

open http://localhost:3000/d/B2zGKKs7k # Open Grafana simnet dashboard
open http://localhost:16686            # Open Jaeger dashboard

Creating a DKG based cluster that uses locally built binary:

compose new --keygen=dkg --build-local
compose auto

Creating a cluster splitting existing keys for a public testnet:

# Prep the keys to split
# Each keystore-{foo}.json requires a keystore-{foo}.txt file containing the password.
mkdir mykeys
cp path/to/existing/keys/keystore-*.json mykeys/
cp path/to/passwords/keystore-*.txt mykeys/

compose new --split-keys-dir=mykeys --beacon-node=$BEACON_URL
compose auto

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Auto added in v0.12.0

func Auto(ctx context.Context, conf AutoConfig) error

Auto runs all three steps (define,lock,run) sequentially with support for detecting alerts.

func Clean

func Clean(ctx context.Context, dir string) error

Clean deletes all compose directory files and artifacts.

func New

func New(ctx context.Context, dir string, conf Config) error

New creates a new compose config file from flags.

func NewRunnerFunc added in v0.12.0

func NewRunnerFunc(topic string, dir string, up bool, runFunc RunFunc,
) func(ctx context.Context) (data TmplData, err error)

NewRunnerFunc returns a function that wraps and runs a run function.

func WriteConfig added in v0.6.0

func WriteConfig(dir string, conf Config) error

WriteConfig writes the config as yaml to disk.

func WriteDockerCompose

func WriteDockerCompose(dir string, data TmplData) error

WriteDockerCompose generates the docker-compose.yml template and writes it to disk.

Types

type AutoConfig added in v0.12.0

type AutoConfig struct {
	// Dir is the directory to use for compose artifacts.
	Dir string
	// AlertTimeout is the timeout to collect alerts before shutdown. Zero disables timeout.
	AlertTimeout time.Duration
	// SudoPerms enables changing all compose artefacts file permissions using sudo.
	SudoPerms bool
	// Print generated docker-compose.yml files.
	PrintYML bool
	// RunTmplFunc allows arbitrary overrides in the run step template.
	RunTmplFunc func(*TmplData)
	// DefineTmplFunc allows arbitrary overrides if the define step template.
	DefineTmplFunc func(*TmplData)
	// LogFile enables writing (appending) docker-compose output to this file path instead of stdout.
	LogFile string
}

type Config

type Config struct {
	// Version defines the compose config version.
	Version string `json:"version"`

	// Step defines the current completed compose step.
	Step step `json:"step"`

	// NumNodes is the number of charon nodes in the cluster.
	NumNodes int `json:"num_nodes"`

	// Threshold required for signature reconstruction. Defaults to safe value for number of nodes/peers.
	Threshold int `json:"threshold"`

	// NumValidators is the number of DVs (n*32ETH) to be created in the cluster lock file.
	NumValidators int `json:"num_validators"`

	// ImageTag defines the charon docker image tag: obolnetwork/charon:{ImageTag}.
	ImageTag string `json:"image_tag"`

	// BuildBinary enables building a local charon binary from source and using that in the containers.
	BuildBinary bool `json:"build_binary"`

	// PrebuiltBinary enables using a prebuilt local charon binary to use in the containers.
	PrebuiltBinary bool `json:"prebuilt_binary"`

	// KeyGen defines the key generation process.
	KeyGen KeyGen `json:"key_gen"`

	// SplitKeysDir directory containing keys to split for keygen==create.
	SplitKeysDir string `json:"split_keys_dir"`

	// BeaconNode url endpoint or "mock" for simnet.
	BeaconNode string `json:"beacon_node"`

	// ExternalBootnode HTTP url endpoint or empty to disable.
	ExternalBootnode string `json:"external_bootnode"`

	// VCs define the types of validator clients to use.
	VCs []VCType `json:"validator_clients"`

	// FeatureSet defines the minimum feature set to enable.
	FeatureSet string `json:"feature_set"`

	// DisableMonitoringPorts defines whether to disable prometheus and jaeger monitoring port binding.
	DisableMonitoringPorts bool `json:"disable_monitoring_ports"`

	// InsecureKeys generates insecure keys. Useful when testing large validator sets
	// as it speeds up keystore encryption and decryption.
	InsecureKeys bool `json:"insecure_keys"`
}

Config defines a local compose cluster; including both keygen and running a cluster.

func LoadConfig

func LoadConfig(dir string) (Config, error)

LoadConfig returns the config loaded from disk.

func NewDefaultConfig

func NewDefaultConfig() Config

NewDefaultConfig returns a new default config.

func (Config) VCStrings added in v0.10.1

func (c Config) VCStrings() []string

VCStrings returns the VCs field as a slice of strings.

type KeyGen

type KeyGen string

KeyGen defines a key generation process.

const (
	KeyGenDKG    KeyGen = "dkg"
	KeyGenCreate KeyGen = "create"
)

type RunFunc added in v0.12.0

type RunFunc func(context.Context, string, Config) (TmplData, error)

RunFunc defines a function that generates docker-compose.yml from config and returns the template data.

type TmplData

type TmplData struct {
	ComposeDir string

	CharonImageTag   string
	CharonEntrypoint string
	CharonCommand    string

	Nodes []TmplNode
	VCs   []TmplVC

	Bootnode        bool
	Monitoring      bool
	MonitoringPorts bool
}

TmplData is the docker-compose.yml template data.

func Define

func Define(ctx context.Context, dir string, conf Config) (TmplData, error)

Define defines a compose cluster; including both keygen and running definitions.

func Lock

func Lock(ctx context.Context, dir string, conf Config) (TmplData, error)

Lock creates a docker-compose.yml from a charon-compose.yml for generating keys and a cluster lock file.

func Run

func Run(ctx context.Context, dir string, conf Config) (TmplData, error)

Run creates a docker-compose.yml from config.json to run the cluster.

type TmplNode added in v0.10.0

type TmplNode struct {
	ImageTag   string // ImageTag is empty by default, resulting in CharonImageTag being used.
	Entrypoint string // Entrypoint is empty by default, resulting in CharonEntrypoint being used.
	EnvVars    []kv
	Ports      []port
}

TmplNode represents a charon TmplNode service in a docker-compose.yml.

type TmplVC added in v0.10.0

type TmplVC struct {
	Label   string
	Image   string
	Build   string
	Command string
	Ports   []port
}

TmplVC represents a validator client service in a docker-compose.yml.

type VCType added in v0.6.0

type VCType string

VCType defines a validator client type.

const (
	VCMock       VCType = "mock"
	VCTeku       VCType = "teku"
	VCLighthouse VCType = "lighthouse"
)

Directories

Path Synopsis
Command compose provides a tool to run, test, debug local charon clusters using docker-compose.
Command compose provides a tool to run, test, debug local charon clusters using docker-compose.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL