Skip to main content
Before starting the tutorial, make sure you have the following tools installed.
This tutorial is intended for macOS and Linux systems. Other systems may have additional requirements.

​
Go

The example chain requires Go 1.25 or higher.
If Go is not installed, download it from go.dev/dl.

​
Configure Go Environment Variables

After installing Go, make sure $GOPATH/bin is on your PATH so installed binaries (like exampled) are accessible. Open your shell config file (~/.zshrc on macOS or ~/.bashrc on Linux) and add:
Then apply the changes:
Verify: go env GOPATH

​
Make

Make is used to run build and development commands throughout the tutorial.
Make is pre-installed on most Linux and macOS systems. If it is missing:
  • macOS: xcode-select --install
  • Linux (Debian/Ubuntu): sudo apt install build-essential

​
Docker

Docker is required to run make proto-gen, which generates Go code from the module’s proto files using buf.
Download Docker from docs.docker.com/get-docker. Docker must be running before you execute make proto-gen.

​
Git

​
Clone the repository

Clone cosmos/example and navigate into it:
The repo has two branches used in this tutorial series:
  • main — the complete chain with the full x/counter module wired in.
  • tutorial/start — the same chain with the counter module stripped out. Start here if you want to build the module yourself from scratch.

​
Repository Layout

After cloning, the repository looks like this:

​
Where things live

The tutorials in this section will walk you through the most common kinds of chain changes and show you where they usually live in the repo:
  • Add or modify a module: x/<module>/ and proto/
  • Wire a module into the chain: app.go
  • Change the binary or CLI: exampled/
  • Run the chain or tests: Makefile targets
Next: Quickstart →