Capsule configuration docs

Capsule is a tool that allows you to run a custom network simulation locally on single a machine. It is an incredibly useful tool for anybody who wants to try experimenting on or with a Vega network without using a real network.

The configuration for Capsule is used to generate and bootstrap commands, and can be customised to fit your personal need. Under the hood, Capsule uses this configuration to generate a new network and store all its files in a single directory. You can then use Nomad to deploy all generated services from the generation step. Nomad is built into the Capsule binaries.

The configuration uses the HCL language syntax, which is also used, for example, by Terraform.

This document explains all possible configuration options in Capsule.

Root - Config

All parameters from this types are used directly in the config file. Most of the parameters here are optional and can be left alone. Please see the example below.

Fields

network NetworkConfig - required, block

Configuration of Vega network and its dependencies.

output_dir string - optional

Directory path (relative or absolute) where Capsule stores generated folders, files, logs and configurations for network.

Default value: ~/.vegacapsule/testnet

vega_binary_path string - optional

Path (relative or absolute) to vega binary that will be used to generate and run the network.

Default value: vega

vega_capsule_binary_path string - optional

Path (relative or absolute) of a Capsule binary. The Capsule binary is used to aggregate logs from running jobs and save them to local disk in Capsule home directory. See vegacapsule nomad logscollector for more info.

Default value: Currently running Capsule instance binary

This optional parameter is used internally. There should never be any need to set it to anything other than default.

Complete example

vega_binary_path = "/path/to/vega"

network "your_network_name" {
  ...
}

NetworkConfig

Network configuration allows a user to customise the Capsule Vega network into different shapes based on personal needs. It also allows the configuration and deployment of different Vega nodes' setups (validator, full - full means a non validating node) and their dependencies (like Ethereum or Postgres). It can run custom Docker images before and after the network nodes have started and much more.

Fields

name string - required, label

Name of the network. All folders generated are placed in the folder with this name. All Nomad jobs are prefixed with this name.

genesis_template string - required | optional if genesis_template_file defined

Go template of the genesis file that will be used to bootrap the Vega network. Example of templated mainnet genesis file.

The GenesisTemplateContext can be used in the template. Example example.

It is recommended that you use `genesis_template_file` param instead. If both `genesis_template` and `genesis_template_file` are defined, then `genesis_template` overrides `genesis_template_file`.

`genesis_template` example

genesis_template = <<EOH
 {
  "app_state": {
   ...
  }
  ..
 }
EOH

genesis_template_file string - optional

Same as genesis_template but it allows the user to link the genesis file template as an external file.

`genesis_template_file` example

genesis_template_file = "/your_path/genesis.tmpl"

genesis_template_url string - optional

Same as genesis_template but it allows the user to download a template file from the URL

`genesis_template_url` example

genesis_template_url = "https://example.com/genesis.json.tmpl"

ethereum EthereumConfig - required, block

Allows the user to define the applicable Ethereum network configuration. This is necessary because the Vega network needs to be connected to Ethereum bridges or it cannot function.

`ethereum` example

ethereum {
  ...
}

smart_contracts_addresses string - required | optional if smart_contracts_addresses_file defined, optional

Smart contract addresses are addresses of Ethereum bridge contracts in JSON format.

These addresses need to correspond to the chosen network in Ethereum network and can be used in various types of templates in Capsule. Example of smart contract address from mainnet.

It is recommended that you use the `smart_contracts_addresses_file` param instead. If both `smart_contracts_addresses` and `smart_contracts_addresses_file` are defined, then `genesis_template` overrides `smart_contracts_addresses_file`.

`smart_contracts_addresses` example

smart_contracts_addresses = <<EOH
 {
  "erc20_bridge": "...",
  "staking_bridge": "...",
  ...
 }
EOH

smart_contracts_addresses_file string - optional

Same as smart_contracts_addresses but it allows you to link the smart contracts as an external file.

`smart_contracts_addresses_file` example

smart_contracts_addresses_file = "/your_path/smart-contratcs.json"

node_set []NodeConfig - required, block

Allows a user to define multiple node sets and their specific configurations. A node set is a representation of Vega and Data Node nodes. The node set is the essential building block of the Vega network.

`node_set` example

Validators node set

node_set "validator-nodes" {
  ...
}

Full nodes node set

node_set "full-nodes" {
  ...
}

wallet WalletConfig - optional, block

Allows for deploying and configuring the Vega Wallet instance. Wallet will not be deployed if this block is not defined.

`wallet` example

wallet "wallet-name" {
  ...
}

faucet FaucetConfig - optional, block

Allows for deploying and configuring the Vega Core Faucet instance, for supplying builtin assets. Faucet will not be deployed if this block is not defined.

`faucet` example

faucet "faucet-name" {
  ...
}

pre_start PStartConfig - optional, block

Allows the user to define jobs that should run before the node sets start. It can be used for node sets' dependencies, like databases, mock Ethereum chain, etc..

`pre_start` example

pre_start {
  docker_service "ganache-1" {
    ...
  }
  docker_service "ganache-2" {
    ...
  }
  docker_service "postgres-1" {
    ...
  }
}

post_start PStartConfig - optional, block

Allows the user to define jobs that should run after the node sets start. It can be used for services that depend on a network that is already running, like block explorer or Console.

`post_start` example

post_start {
  docker_service "bloc-explorer-1" {
    ...
  }
  docker_service "vega-console-1" {
    ...
  }
}

Complete example

network "testnet" {
  ethereum {
    ...
  }
  secondary_ethereum {
    ...
  }

  pre_start {
    ...
  }

  genesis_template_file          = "..."
  smart_contracts_addresses_file = "..."

  node_set "validator-nodes" {
    ...
  }

  node_set "full-nodes" {
    ...
  }
}

EthereumConfig

Allows the user to define the specific primary Ethereum network to be used. It can either be one of the public networks or a local instance of Ganache.

Fields

chain_id string - required
network_id string - required
endpoint string - required

SecondaryEthereumConfig

Allows the user to define the specific secondary Ethereum network to be used. It can either be one of the public networks or a local instance of Ganache.

Fields

chain_id string - required
network_id string - required
endpoint string - required

NodeConfig

Represents, and allows the user to configure, a set of Vega (with Tendermint) and Data Node nodes. One node set definition can be used by applied to multiple node sets (see count field) and it uses templating to distinguish between different nodes and names/ports and other collisions.

Fields

name string - required, label

Name of the node set. Nomad instances that are part of these nodes are prefixed with this name.

mode string - required

Determines what mode the node set should run in.

Valid values:

validator
full

count int - required

Defines how many node sets with this exact configuration should be created.

node_wallet_pass string - optional | required if mode=validator defined

Defines the password for the automatically generated node wallet associated with the created node.

ethereum_wallet_pass string - optional | required if mode=validator defined

Defines password for automatically generated Ethereum wallet in node wallet.

vega_wallet_pass string - optional | required if mode=validator defined

Defines password for automatically generated Vega wallet in node wallet.

use_data_node bool - optional

Whether or not Data Node should be deployed on node set.

visor_binary string - optional

Path to Visor binary. If defined, Visor is automatically used to deploy Vega and Data nodes. The relative or absolute path can be used, if only the binary name is defined it automatically looks for it in $PATH.

config_templates ConfigTemplates - required, block

Templates that can be used for configurations of Vega and Data nodes, Tendermint and other services.

vega_binary_path string - optional

Allows user to define a Vega binary to be used in specific node set only. A relative or absolute path can be used. If only the binary name is defined, it automatically looks for it in $PATH. This can help with testing different version compatibilities or a protocol upgrade.

Using versions that are not compatible could break the network - therefore this should be used in advanced cases only.

pre_generate PreGenerate - optional, block

Allows a user to run a custom service before the node set is generated. This can be very useful when generating the node set might have some extenal dependency, such as a Clef wallet.

Clef wallet is a good example - since generating a validator node set requires the Ethereum key to be generated, Clef can be started before the generation starts so that Capsule can generate the Ethereum key inside of it during the generation process.

pre_start_probe types.ProbesConfig - optional, block

Allows the user to run checks that have to be fulfilled before the node starts.

This can be useful for checking whether some dependent services have already started or not. Examples: databases, mocked services, etc..

clef_wallet ClefConfig - optional, block

Clef is one of the supported Ethereum wallets for Vega node. Capsule supports using Clef and can automatically import pre-generated Ethereum keys from Clef during node set generation process.

By configuring this paramater, Capsule will automatically generate Ethereum keys in Clef and tell Vega to use them. An example Capsule config setup with Clef can be seen in config_clef.

nomad_job_template string - optional

Go template of custom Nomad job for node set.

By default Capsule uses predefined Nomad jobs to run the node set on Nomad. This parameter allows users to provide a custom Nomad job to represent the generated node set.

The types.NodeSet can be used in the template.

Using custom Nomad jobs for node sets can break Capsule functionality. Very detailed knowledge is required - therefore it is not recommend to use this parameter unless you are an advanced user.

It is recommended that you use `nomad_job_template_file` param instead. If both `nomad_job_template` and `nomad_job_template_file` are defined, then `vega` overrides `nomad_job_template_file`.

nomad_job_template_file string - optional

Same as nomad_job_template but it allows the user to link the Nomad job template as an external file.

`nomad_job_template_file` example

nomad_job_template_file = "/your_path/vega_config.tmpl"

Complete example

node_set "validators" {
  count = 2
  mode  = "validator"

  node_wallet_pass     = "n0d3w4ll3t-p4ssphr4e3"
  vega_wallet_pass     = "w4ll3t-p4ssphr4e3"
  ethereum_wallet_pass = "ch41nw4ll3t-3th3r3um-p4ssphr4e3"

  config_templates {
    vega_file       = "./path/vega_validator.tmpl"
    tendermint_file = "./path/tendermint_validator.tmpl"
  }
}

WalletConfig

Represents a configuration of a Vega Wallet service.

Fields

name string - required, label

Name of the wallet. It will be used as an identifier when wallet runs.

vega_binary_path string - optional

By default, the wallet config inherits the Vega binary from the main network config, but this parameter allows a user to define a different Vega binary to be used in wallet. This can be used if a different wallet version is required. A relative or absolute path can be used. If only the binary name is defined, it automatically looks for it in $PATH.

Using a Vega wallet version that is not compatible with the network version will not work - therefore this should be used in advanced cases only.

token_passphrase_path string - optional

Path to the file that contains the password used to protect the API token to wallet. API tokens are keys linked to a wallet that allow third party apps and bots to connect and send transactions without the need for user interaction. If this value is not defined, api tokens will not be enabled. A relative or absolute path can be used.

template string - optional

Go template of a Vega Wallet config.

The wallet.ConfigTemplateContext can be used in the template. Example can be found in default network config.

`template` example

template = <<EOH
 ...
EOH

Complete example

wallet "wallet-1" {
  template = <<-EOT
  ...
 EOT

}

FaucetConfig

Represents a configuration of a Vega Faucet service.

Fields

name string - required, label

Name of the faucet. It will be used as an identifier when the faucet runs.

wallet_pass string - required

Passphrase for the wallet.

template string - optional

Go template of a Vega Faucet config.

The faucet.ConfigTemplateContext can be used in the template. Example can be found in default network config.

`template` example

template = <<EOH
 ...
EOH

Complete example

faucet "faucet-1" {
{
wallet_pass = "wallet_pass"
template = <<-EOT
  ...
 EOT
}

PStartConfig

Allows the user to configure services that will run before or after the network starts.

Fields

docker_service []DockerConfig - required, block: Allows the user to define multiple services to be run inside Docker.
exec_service []ExecConfig - required, block

ConfigTemplates

Allow to add configuration template for certain services deployed by Capsule. Learn more about how configuration templating work here

Fields

vega string - required | optional if vega_file defined, optional

Go template of Vega config.

The vega.ConfigTemplateContext can be used in the template. Example example.

It is recommended that you use `vega_file` param instead. If both `vega` and `vega_file` are defined, then `vega` overrides `vega_file`.

`vega` example

vega = <<EOH
 ...
EOH

vega_file string - optional

Same as vega but it allows the user to link the Vega config template as an external file.

`vega_file` example

vega_file = "/your_path/vega_config.tmpl"

tendermint string - required | optional if tendermint_file defined, optional

Go template of Tendermint config.

The tendermint.ConfigTemplateContext can be used in the template. Example example.

It is recommended that you use `tendermint_file` param instead. If both `tendermint` and `tendermint_file` are defined, then `tendermint` overrides `tendermint_file`.

`tendermint` example

tendermint = <<EOH
 ...
EOH

tendermint_file string - optional

Same as tendermint but it allows the user to link the Tendermint config template as an external file.

`tendermint_file` example

tendermint_file = "/your_path/tendermint_config.tmpl"

data_node string - required | optional if data_node_file defined, optional

Go template of Data Node config.

The datanode.ConfigTemplateContext can be used in the template. Example example.

It is recommended that you use `data_node_file` param instead. If both `data_node` and `data_node_file` are defined, then `data_node` overrides `data_node_file`.

data_node_file string - optional

Same as data_node but it allows the user to link the Data Node config template as an external file.

visor_run_conf string - required | optional if visor_run_conf_file defined, optional

Go template of Visor genesis run config.

The visor.ConfigTemplateContext can be used in the template. Example example.

Current Vega binary is automatically copied to the Visor genesis folder by Capsule so it can be used from this template.

It is recommended that you use `visor_run_conf_file` param instead. If both `visor_run_conf` and `visor_run_conf_file` are defined, then `visor_run_conf` overrides `visor_run_conf_file`.

visor_run_conf_file string - optional

Same as visor_run_conf but it allows the user to link the Visor genesis run config template as an external file.

visor_conf string - required | optional if visor_conf_file defined, optional

Go template of Visor config.

The visor.ConfigTemplateContext can be used in the template. Example example.

It is recommended that you use `visor_conf_file` param instead. If both `visor_conf` and `visor_conf_file` are defined, then `visor_conf` overrides `visor_conf_file`.

visor_conf_file string - optional

Same as visor_conf but it allows the user to link the Visor genesis run config template as an external file.

PreGenerate

Allows to define service that will run before generation step.

Fields

nomad_job []NomadConfig - required, block: Allows to define raw Nomad jobs.

ClefConfig

Allows to configure connetion to Clef Ethereum wallet.

Fields

ethereum_account_addresses []string - required: List of Clef pre-generated Ethereum addresses that can be used by node set.

There should be enough available addresses for each node set. So when node set has `count = 2` there has to be minimum 2 addresses defined similarly when `count = 4` there has to be minimum 4 addresses defined etc.
clef_rpc_address string - required: Address of running Clef instance

DockerConfig

Allows the user to configure Docker container services that will run before or after the Vega network starts.

Fields

name string - required, label: Name of the service that is going to be used as an identifier when service runs.
image string - required: Name of publicly available Docker image.
cmd string - optional: Command that will run at the image startup.
args []string - required: List of arguments that will be added to cmd.
env map[string]string - optional: Allows the user to set environment varibles for the container.
static_port StaticPort - optional, block: Allows the user to open a static port from container to host.
auth_soft_fail bool - optional: Defines whether or not the task fails on an authentication failure.

Should be always `true` for public images.
resources Resources - optional, block: Allows the user to define the minimum required hardware resources for the container.
volume_mounts []string - optional

ExecConfig

Fields

name string - required, label: Name of the service that is going to be used as an identifier when service runs.
cmd string - optional: Command that will run
args []string - required: List of arguments that will be added to cmd.
env map[string]string - optional: Allows the user to set environment variables launched process.

NomadConfig

Allows the user to configure a Nomad job definition to be run on Capsule.

Fields

name string - required, label

Name of the Nomad job.

job_template string - required | optional if job_template_file defined, optional

Go template of a Nomad job template.

The nomad.PreGenerateTemplateCtx can be used in the template. Example example.

It is recommended that you use `job_template_file` param instead. If both `job_template` and `job_template_file` are defined, then `job_template` overrides `job_template_file`.

`job_template` example

job_template = <<EOH
 ...
EOH

job_template_file string - optional

Same as job_template but it allows the user to link the Nomad job template as an external file.

`job_template_file` example

job_template_file = "/your_path/nomad-job.tmpl"

Complete example

nomad_job "clef" {
  job_template = "/path-to/nomad-job.tmpl"
}

StaticPort

Represents static port mapping from host to container.

Fields

value int - required: Represents port value on the host.
to int - optional: Represents port value inside of the container.

Resources

Allows the user to define hardware resource requirements

Fields

cpu int - optional: Minimum required CPU in MHz
cores int - optional: Number of minimum required CPU cores
memory int - optional: Minimum required RAM in Mb
memory_max int - optional: Maximum allowed RAM in Mb
disk int - optional: Minimum required disk space in Mb

Files

config.md

Latest commit

History

config.md

File metadata and controls

Capsule configuration docs

Root - Config

Fields

Complete example

NetworkConfig

Fields

genesis_template example

genesis_template_file example

genesis_template_url example

ethereum example

smart_contracts_addresses example

smart_contracts_addresses_file example

node_set example

wallet example

faucet example

pre_start example

post_start example

Complete example

EthereumConfig

Fields

Complete example

SecondaryEthereumConfig

Fields

Complete example

NodeConfig

Fields

nomad_job_template_file example

Complete example

WalletConfig

Fields

template example

Complete example

FaucetConfig

Fields

template example

Complete example

PStartConfig

Fields

Complete example

ConfigTemplates

Fields

vega example

vega_file example

tendermint example

tendermint_file example

PreGenerate

Fields

Complete example

ClefConfig

Fields

Complete example

DockerConfig

Fields

Complete example

ExecConfig

Fields

NomadConfig

Fields

job_template example

job_template_file example

Complete example

StaticPort

Fields

Complete example

Resources

Fields

Complete example

`genesis_template` example

`genesis_template_file` example

`genesis_template_url` example

`ethereum` example

`smart_contracts_addresses` example

`smart_contracts_addresses_file` example

`node_set` example

`wallet` example

`faucet` example

`pre_start` example

`post_start` example

`nomad_job_template_file` example

`template` example

`template` example

`vega` example

`vega_file` example

`tendermint` example

`tendermint_file` example

`job_template` example

`job_template_file` example