Skip to content
Aptos Documentation

Running Locally

When building a custom processor, you might find it helpful to develop against a local development stack. The Transaction Stream Service is a complicated, multi-component system. To assist with local development, we offer a Python script that wraps a Docker compose file to set up the entire system.

This script sets up the following:

  • Single node testnet with the indexer GRPC stream enabled.
  • A Redis instance.
  • Transaction Stream Service, including the following components:
    • cache-worker: Pulls transactions from the node and stores them in Redis.
    • file-store: Fetches transactions from Redis and stores them in a filesystem.
    • data-service: Serves transactions via a GRPC stream to downstream clients. It pulls from either the cache or the file store depending on the age of the transaction.
  • Shared volumes and networking to hook it all up.

You can learn more about the Transaction Stream Service architecture here and the Docker compose file here.

Prerequisites

Section titled “Prerequisites”

In order to use the local development script you must have the following installed:

Terminal window
docker-compose version --short

Preparation

Section titled “Preparation”

Clone the aptos-core repo:

Terminal window
# HTTPS
git clone https://github.com/aptos-labs/aptos-core.git


# SSH
git clone git@github.com:aptos-labs/aptos-core.git

Navigate to the testsuite directory:

Terminal window
cd aptos-core
cd testsuite

Install the Python dependencies:

Terminal window
poetry install

Running the script

Section titled “Running the script”

Starting the service

Section titled “Starting the service”
Terminal window
poetry run python indexer_grpc_local.py start

You will know this succeeded if the command exits, and you see the following:

Terminal window
Attempting to stream from indexer grpc for 10s
Stream finished successfully

Stopping the service

Section titled “Stopping the service”
Terminal window
poetry run python indexer_grpc_local.py stop

Wiping the data

Section titled “Wiping the data”

When you start, stop, and start the service again, it will re-use the same localnet data. If you wish to wipe the locnet and start from scratch you can run the following command:

Terminal window
poetry run python indexer_grpc_local.py wipe

Using the local service

Section titled “Using the local service”

You can connect to the local Transaction Stream Service, e.g. from a custom processor, using the following configuration values:

Terminal window
indexer_grpc_data_service_address: 127.0.0.1:50052
auth_token: dummy_token

You can connect to the node at the following address:

Terminal window
http://127.0.0.1:8080/v1

Debugging

Section titled “Debugging”

Usage on ARM systems

Section titled “Usage on ARM systems”

If you have a machine with an ARM processor, e.g. an M1/M2 Mac, the script should detect that and set the appropriate environment variables to ensure that the correct images will be used. If you have issues with this, try setting the following environment variable:

Terminal window
export DOCKER_DEFAULT_PLATFORM=linux/amd64

Additionally, make sure the following settings are correct in Docker Desktop:

  • Enabled: Preferences > General > Use Virtualization framework
  • Enabled: Preferences > General > Use Docker Compose V2
  • Disabled: Features in development -> Use Rosetta for x86/amd64 emulation on Apple Silicon

This script has not been tested on Linux ARM systems.

Redis fails to start

Section titled “Redis fails to start”

Try setting the following environment variable before running the script:

Terminal window
export REDIS_IMAGE_REPO=arm64v8/redis

Cache worker is crash-looping or Redis latest version update failed. in log

Section titled “Cache worker is crash-looping or Redis latest version update failed. in log”

Wipe the data:

Terminal window
poetry run python indexer_grpc_local.py wipe

This means historical data will be lost.