# What is LocalOsmosis?
LocalOsmosis (a fork of LocalTerra) is a complete Osmosis testnet and ecosystem containerized with Docker and orchestrated with a simple
docker-compose file. It simplifies the way smart-contract developers test their contracts in a sandbox before they deploy them on a testnet or mainnet.
LocalOsmosis comes preconfigured with opinionated, sensible defaults for standard testing environments. If other projects mention testing on LocalOsmosis, they are referring to the settings defined in this repo.
LocalOsmosis has the following advantages over a public testnet:
- Easily modifiable world states
- Quick to reset for rapid iterations
- Simple simulations of different scenarios
- Controllable validator behavior
Docker(opens new window)
docker-compose(opens new window)
Osmosisd(opens new window)
- Select option 3 (localosmosis), the installer will configure everything for you.
- The osmosisd dameon on your local computer is used to communicate with the localosmosis daemin running inside the Docker container.
- Supported known architecture: x86_64
- 16+ GB of RAM is recommended
# Install LocalOsmosis
- Run the following commands::
git clone https://github.com/osmosis-labs/LocalOsmosis.git cd LocalOsmosis
- Make sure your Docker daemon is running in the background and
docker-compose(opens new window) is installed.
If running on linux, you can install these tools with the following commands:
sudo apt-get remove docker docker-engine docker.io sudo apt-get update sudo apt install docker.io -y
sudo apt install docker-compose -y
# Start, stop, and reset LocalOsmosis
- Start LocalOsmosis:
Your environment now contains:
- osmosisd (opens new window) RPC node running on
- LCD running on http://localhost:1317
Stop LocalOsmosis (and retain chain data):
Stop LocalOsmosis (and delete chain data):
Ensure the same version of
osmosisdis present in your local computer and LocalOsmosis Docker container. You can check the version of localosmosis by checking the image in the docker-compose.yml file and the version of your osmosisd on your local machine with
osmosisdfrom your local machine to talk to your LocalOsmosis
This command automatically works because
osmosisd connects to
localhost:26657 by default.
The following command is the explicit form:
osmosisd status --node=tcp://localhost:26657
- Run any of the
osmosisdcommands against your LocalOsmosis network, as shown in the following example:
osmosisd query account osmo1l0jjmvdtj4c3f8cxzzgfhq0zhdzf2x8cgpg056
# Configure LocalOsmosis
The majority of LocalOsmosis is implemented through a
docker-compose.yml file, making it easily customizable. You can use LocalOsmosis as a starting template point for setting up your own local Osmosis testnet with Docker containers.
Out of the box, LocalOsmosis comes preconfigured with opinionated settings such as:
- ports defined for RPC (26657) and LCD (1317)
- standard accounts
# Modifying node configuration
You can modify the node configuration of your validator in the
# Pro tip: Speed Up Block Time
To decrease block time, edit the
[consensus] parameters in the
config/config.toml file, and specify your own values.
The following example configures all timeouts to
##### consensus configuration options ##### [consensus] wal_file = "data/cs.wal/wal" - timeout_propose = "3s" - timeout_propose_delta = "500ms" - timeout_prevote = "1s" - timeout_prevote_delta = "500ms" - timeout_precommit_delta = "500ms" - timeout_commit = "5s" + timeout_propose = "200ms" + timeout_propose_delta = "200ms" + timeout_prevote = "200ms" + timeout_prevote_delta = "200ms" + timeout_precommit_delta = "200ms" + timeout_commit = "200ms"
Additionally, you can use the following single line to configure timeouts:
sed -E -i '/timeout_(propose|prevote|precommit|commit)/s/[0-9]+m?s/200ms/' config/config.toml
# Modifying genesis
You can change the
genesis.json file by altering
config/genesis.json. To load your changes, restart your LocalOsmosis.
LocalOsmosis is pre-configured with one validator and 10 accounts with ION and OSMO balances.
# Common issues
# Docker permissions problems
In case you get permission denied while trying to run
make start Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get http://%2Fvar%2Frun%2Fdocker.sock/v1.40/containers/json: dial unix /var/run/docker.sock: connect: permission denied
Check that the docker engine is running:
sudo systemctl status docker
# Configure Docker to start on boot sudo systemctl enable docker.service # Start docker service sudo systemctl start docker.service
Ensure that the current user is in the
- Create the docker group and add your user
# Create the docker group sudo groupadd docker # Add your user to the docker group. sudo usermod -aG docker $USER
- Log out and log back in so that your group membership is re-evaluated.
More details can be found here (opens new window).