This tutorial will teach you how to install AlgoSearch using docker compose and use it locally on Algorand’s sandbox-net as well as to connect it to an external archival node (if you have one).

There is also a video walk-through

When a developer uses sandbox-net on their private sandbox, transactions have not, up until this point been available on TestNet Explorers for viewing. This results in having to run goal commands to query. This tutorial will show how to use sandbox and have an explorer in private network mode.

DEPRECATED CONTENT: Switch to DappFlow

This content is deprecated.
If you need a block explorer for Algorand sandbox-net, DappFlow is the recommended option.

1. Installing AlgoSearch

1. Create a directory on your local machine to clone the repository into.
2. clone the repository into your intended directory by navigating to the directory in your command line and running git clone https://github.com/kevguy/algosearch.git
3. if you have any instances of CouchDB running then close them (they may conflict with the CouchDB instance that will be created by Docker compose).

Congratulations you now have AlgoSearch installed!

2. Configuring AlgoSearch for Sandbox-net

In order to run AlgoSearch with sandbox-net you will need to replace the docker-compose.yml file in your local Sandbox repository with our version found in the directory algosearch/sandbox_files of your AlgoSearch repository or downloaded separately here. In this file we have added a new network called “sandbox-shared-network” and the host and network for every single service so they can be accessed by another Docker compose network (i.e. by AlgoSearch).

After this change has been made spin up Sandbox as usual in git bash with the command:
./sandbox up -v

This will allow you to test if sandbox is still working.

Next go to your local AlgoSearch repository and run docker network ls in your command line and you should see a table appear that includes a network with the name “sandbox_sandbox-shared-network” this shows that we can bridge all the containers we have in AlgoSearch’s Docker compose with sandbox’s network.

3. Running AlgoSearch With Sandbox-net

In the AlgoSearch repository if you have Make installed run the command make up to begin building the Docker images. If Make is not installed then use the following command docker-compose -f zarf/compose/compose.yaml -f zarf/compose/compose-config.yaml up --detach --remove-orphans to do the same thing.

Wait for a minute because it will take a bit longer than the feedback from the command line suggests for CouchDB to be set up. To check that CouchDB is set up:

1. go to localhost:5984/_utils/#login and
2. log in with username “algorand” and password “algorand”
3. check the Database Name, there should be two “_users” and “algo_global”, “algo_global” should have at least 5 # of Docs. Once you have finished setting AlgoSearch up and begin using it you can come back to this to review the data stored in the backend (if you want to).

To check that AlgoSearch is working go to localhost:3000 in your browser, and you should see something like the image at the start of this tutorial. You will notice that there are no transactions yet (the column on the left), so you will have to make one.

Go back to the bash terminal that you are running sandbox in and you will see that sandbox has given you an example of a transaction you can send that looks like:

./sandbox goal clerk send -a 123456789 -f [account 1] -t [account 2]

run this command to send the transaction.

Wait for the blocks in the sandbox-net to sync up with the blocks in CouchDB. When this is done you will see the transaction appear on the AlgoSearch dashboard (a transaction will appear in the column on the left).

Congratulations, AlgoSearch is now working with Sandbox!

Note: You may receive this error running on a Mac running Mac OS Monterery as follows:

Ports are not available: listen tcp 0.0.0.0:5000: bind: address already in use

The process running on this port turns out to be an AirPlay server. Killing it will not do any good and it will just autostart it again by the system. You can deactivate it as follows:

System Preferences › Sharing , and unchecking AirPlay Receiver to release port 5000.

4. Other Commands

To stop running AlgoSearch, navigate to your repository in the command line and give the command make down, or if you do not have Make installed docker-compose -f zarf/compose/compose.yaml down --remove-orphans.

To get the logs run make logs or if you do not have Make installed docker-compose -f zarf/compose/compose.yaml logs -f

5. Running AlgoSearch With External Archival Node

The steps to achieve this are all the same except the AlgoSearch repository configurations in compose-config.yaml are slightly different, you need to change these variables only (leave the others as they are):

services:
    algosearch-backend:
        ...
        ALGOSEARCH_COUCH_DB_INIT: "false"
        ALGOSEARCH_COUCH_DB_MIGRATE: "false"
        ALGOSEARCH_COUCH_DB_HOST: [ip address]:5984
        ALGOSEARCH_ALGOD_PROTOCOL: "[http OR https]"
        ALGOSEARCH_ALGOD_ADDR: "[ip address]:4001"
        ALGOSEARCH_ALGOD_TOKEN: "[something]"
        ...

    algosearch-frontend:
        ALGOSEARCH_ALGOD_PROTOCOL: "[http OR https]"
        ALGOSEARCH_ALGOD_ADDR: "[ip address]:4001"
        ALGOSEARCH_ALGOD_TOKEN: "[something]"