Terra migration guides
Visit the migration guide to learn how to migrate from Terra Classic to the new Terra blockchain.
Table of Contents
- What is Terra?
- Node Setup
- Set up a production environment
What is Terra?
Terra is a public, open-source, proof-of-stake blockchain. The Terra Core is the reference implementation of the Terra protocol written in Golang. The Terra Core is powered by the Cosmos SDK and Tendermint BFT consensus.
The easiest way to install the Terra Core is to download a pre-built binary. You can find the latest binaries on the releases page.
Step 1: Install Golang
Go v1.18+ or higher is required for The Terra Core.
Install Go 1.18+ from the official site. Ensure that your
GOBINenvironment variables are properly set up by using the following commands:
wget <https://golang.org/dl/go1.18.2.linux-amd64.tar.gz> sudo tar -C /usr/local -xzf go1.18.2.linux-amd64.tar.gz export PATH=$PATH:/usr/local/go/bin export PATH=$PATH:$(go env GOPATH)/bin
export PATH=$PATH:/usr/local/go/bin export PATH=$PATH:$(go env GOPATH)/bin
Confirm your Go installation by checking the version:
Step 2: Get Terra Core source code
Clone the Terra Core from the official repo and check out the
main branch for the latest stable release.
git clone https://github.com/terra-money/core/ cd core git checkout main
Step 3: Build Terra core
Run the following command to install
terrad to your
GOPATH and build the Terra Core.
terrad is the node daemon and CLI for interacting with a Terra node.
# COSMOS_BUILD_OPTIONS=rocksdb make install make install
Step 4: Verify your installation
Verify your installation with the following command:
terrad version --long
A successful installation will return the following:
name: terra server_name: terrad version: <x.x.x> commit: <Commit hash> build_tags: netgo,ledger go: go version go1.18.2 darwin/amd64
terrad is the all-in-one CLI and node daemon for interacting with the Terra blockchain.
To view various subcommands and their expected arguments, use the following command:
$ terrad --help
Stargate Terra App Usage: terrad [command] Available Commands: add-genesis-account Add a genesis account to genesis.json collect-gentxs Collect genesis txs and output a genesis.json file debug Tool for helping with debugging your application export Export state to JSON gentx Generate a genesis tx carrying a self delegation help Help about any command init Initialize private validator, p2p, genesis, and application configuration files keys Manage your application's keys migrate Migrate genesis to a specified target version query Querying subcommands rosetta spin up a rosetta server start Run the full node status Query remote node for status tendermint Tendermint subcommands testnet Initialize files for a terrad testnet tx Transactions subcommands unsafe-reset-all Resets the blockchain database, removes address book files, and resets data/priv_validator_state.json to the genesis state validate-genesis validates the genesis file at the default location or at the location passed as an arg version Print the application binary version information Flags: -h, --help help for terrad --home string directory for config and data (default "/Users/evan/.terra") --log_format string The logging format (json|plain) (default "plain") --log_level string The logging level (trace|debug|info|warn|error|fatal|panic) (default "info") --trace print out full stack trace on errors Use "terrad [command] --help" for more information about a command.
Visit the terrad documentation page for more info on usage.
Once you have
terrad installed, you will need to set up your node to be part of the network.
Join the mainnet
The following requirements are recommended for running a mainnet node:
- Four or more CPU cores
- At least 32 GB of memory
- At least 300 mbps of network bandwidth
- At least 2 TB NVME SSD
- A Linux distribution
Terra node quickstart
terrad init nodename wget -O ~/.terra/config/genesis.json https://cloudflare-ipfs.com/ipfs/QmZAMcdu85Qr8saFuNpL9VaxVqqLGWNAs72RVFhchL9jWs curl https://network.terra.dev/addrbook.json > ~/.terrad/config/addrbook.json terrad start
Join a testnet
Several testnets might exist simultaneously. Ensure that your version of
terrad is compatible with the network you want to join.
To set up a node on the latest testnet, visit the testnet repo.
Run a local testnet
The easiest way to set up a local testing environment is to run LocalTerra, a zero-configuration complete testing environment.
Run a single node testnet
You can also run a local testnet using a single node. On a local testnet, you will be the sole validator signing blocks.
Step 1: Create network and account
First, initialize your genesis file to bootstrap your network. Create a name for your local testnet and provide a moniker to refer to your node:
terrad init --chain-id=<testnet_name> <node_moniker>
Next, create a Terra account by running the following command:
terrad keys add <account_name>
Step 2: Add account to genesis
Add your account to genesis and set an initial balance to start. Run the following commands to add your account and set the initial balance:
terrad add-genesis-account $(terrad keys show <account_name> -a) 100000000uluna terrad gentx <account_name> 10000000uluna --chain-id=<testnet_name> terrad collect-gentxs
Step 3: Run terrad
Now you can start your private Terra network:
terrad node will be running a node on
tcp://localhost:26656, listening for incoming transactions and signing blocks.
Set up a production environment
Note: This guide only covers general settings for a production-level full node. Visit the Terra validator's guide for more information.
This guide has been tested against Linux distributions only. To ensure you successfully set up your production environment, consider setting it up on an Linux system.
Increase maximum open files
terrad can't open more than 1024 files at once.
You can increase this limit by modifying
/etc/security/limits.conf and raising the
* soft nofile 65535 * hard nofile 65535
Create a dedicated user
It is recommended that you run
terrad as a normal user. Super-user accounts are only recommended during setup to create and modify files.
terrad uses several TCP ports for different purposes.
26656: The default port for the P2P protocol. Use this port to communicate with other nodes. While this port must be open to join a network, it does not have to be open to the public. Validator nodes should configure
persistent_peersand close this port to the public.
26657: The default port for the RPC protocol. This port is used for querying / sending transactions and must be open to serve queries from
terrad. DO NOT open this port to the public unless you are planning to run a public node.
1317: The default port for Lite Client Daemon (LCD), which can be enabled in
~/.terra/config/app.toml. The LCD provides an HTTP RESTful API layer to allow applications and services to interact with your
terradinstance through RPC. Check the Terra REST API for usage examples. Don't open this port unless you need to use the LCD.
26660: The default port for interacting with the Prometheus database. You can use Promethues to monitor an environment. This port is closed by default.
Run the server as a daemon
terrad running at all times. The simplest solution is to register
terrad as a
systemd service so that it automatically starts after system reboots and other events.
Register terrad as a service
First, create a service definition file in
[Unit] Description=Terra Daemon After=network.target [Service] Type=simple User=terra ExecStart=/data/terra/go/bin/terrad start Restart=on-abort [Install] WantedBy=multi-user.target [Service] LimitNOFILE=65535
Service section from the given sample above to suit your settings.
Note that even if you raised the number of open files for a process, you still need to include
After creating a service definition file, you should execute
Start, stop, or restart service
systemctl to control (start, stop, restart)
# Start systemctl start terrad # Stop systemctl stop terrad # Restart systemctl restart terrad
# Entire log journalctl -t terrad # Entire log reversed journalctl -t terrad -r # Latest and continuous journalctl -t terrad -f
- Terra docs: Developer documentation.
- Faucet: Get testnet Luna.
- LocalTerra: A dockerized local blockchain testnet.
- Terra Finder: Terra's basic block explorer.
- Agora: Research forum
If you are interested in contributing to Terra Core source, please review our code of conduct.
This software is licensed under the Apache 2.0 license.
© 2022 Terraform Labs, PTE LTD