Awesome

LocalOsmosis

Sunet

The LocalOsmosis repo has been sunset in favor of the LocalOsmosis that lives within the Osmosis repo itself!

Important note

Please note that if you are working with the Osmosis repo you can also easily run a testnet by using some of the make commands, for example:

make localnet-start
make localnet-build

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

Prerequisites

• Docker
• docker-compose
• Osmosisd
  • 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

1. Run the following commands::

git clone https://github.com/osmosis-labs/LocalOsmosis.git
cd LocalOsmosis

2. Make sure your Docker daemon is running in the background and docker-compose is installed.

If running on linux, you can install these tools with the following commands:

• docker

sudo apt-get remove docker docker-engine docker.io
sudo apt-get update
sudo apt install docker.io -y

• docker-compose

sudo apt install docker-compose -y

Start, stop, and reset LocalOsmosis

• Start LocalOsmosis:

make start

Your environment now contains:

• osmosisd RPC node running on tcp://localhost:26657
• LCD running on http://localhost:1317

Stop LocalOsmosis (and retain chain data):

make stop

Stop LocalOsmosis (and delete chain data):

make restart

Integrations

osmosisd

1. Ensure the same version of osmosisd is 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 osmosisd version

2. Use osmosisd from your local machine to talk to your LocalOsmosis osmosisd node:

osmosisd status

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

3. Run any of the osmosisd commands 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 config/config.toml and config/app.toml files.

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 200ms:

##### 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.

Accounts

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

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

If not:

# 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 docker group:

1. 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

2. Log out and log back in so that your group membership is re-evaluated.

More details can be found here.