Setting up an Agoric Dapp Client with docker compose

Notice: agoricdev-8 status

The Agoric beta "devnet" chain agoricdev-8 was started Feb 24 using a more production-like environment where only the BLD holders have the power to start the economic institutions (AMM, vaults, ...). Stay tuned to #4348

Quick Start (Overview)

Note for Incentivized Testnet participants

Some of the following instructions are different if you're on the incentivised testnet. In particular, be sure to:

1. When starting your background ag-solo, use the following docker-compose.yml (not the one for the beta)
2. When registering your client, send your !faucet client agoric1... request to #testnet-faucet not #faucet
3. Use the following to run ag-cosmos-helper commands:

# enter Bash in the container
docker-compose exec ag-solo bash
# list your keys
AGCH="ag-cosmos-helper --home=agorictest-11/ag-cosmos-helper-statedir --keyring-backend=test"
$AGCH keys list
# run other helper commands
$AGCH ...
# exit Bash
exit

0. Install Docker Compose (if you haven't already)
1. Download the latest Beta network docker-compose.yml
2. Start the ag-solo service: docker-compose up -d
3. Watch the logs for registration details: docker-compose logs -f --tail=50
4. Register your client via the Agoric discord faucet
5. Issue an unguessable URL to the wallet: docker-compose exec ag-solo agoric open --repl

See also: Agoric Wallet Set-up Video Walkthrough.

Detailed Instructions

Install Docker Compose

Choose your platform:

• Mac: Install Docker Desktop on Mac
• Windows: Install Docker Desktop on Windows
• Linux: Install Docker Engine and then Install Docker Compose
• Other: Alternative install options

Note: On desktop systems like Docker Desktop for Mac and Windows, Docker Compose is included as part of those desktop installs. You will need to open the application to install docker-compose.

Start background ag-solo

Get docker-compose.yml (for beta / devnet); make sure it's in the current directory of your terminal, and enter the following commands:

docker-compose pull    # get the current image
docker-compose up -d

Watch the logs

Enter this command to watch the logs:

docker-compose logs -f --tail=50

You should see logs like:

ag-solo_1  | 2021-03-23T19:50:25.466Z ag-solo: init: key generated, now extracting address
ag-solo_1  | 2021-03-23T19:50:25.534Z ag-solo: init: ag-solo initialized in /usr/src/agoric-sdk/packages/cosmic-swingset/solo/agoric
ag-solo_1  | 2021-03-23T19:50:25.535Z ag-solo: init: HTTP/WebSocket will listen on 0.0.0.0:8000

Note: visiting 0.0.0.0:8000 without an access token is of little use.

Register your client via the Agoric discord faucet

The ag-solo service will prompt you every few seconds until you register:

ag-solo_1  | =============
ag-solo_1  | agoricdev-1 chain does not yet know of address agoric1l73dgx3yhxc6...
ag-solo_1  | 
ag-solo_1  | Send:
ag-solo_1  | 
ag-solo_1  |   !faucet client agoric1l73dgx3yhxc6...
ag-solo_1  | 
ag-solo_1  | to #faucet channel on https://agoric.com/discord
ag-solo_1  | =============

So visit https://agoric.com/discord , go to the #faucet channel, and enter the message as instructed. After a brief pause, you should see in discord that your request was approved.

Note: Each address can be registered this way only once. If you make another request with the same address, it will be declined.

Your ag-solo log should show:

ag-solo_1  | 2021-03-23T19:51:09.339Z start: swingset running

At this point, you can stop the docker-compose logs process (Control-C).

Open the Agoric wallet using an unguessable URL

Request an unguessable URL using agoric open:

docker-compose exec ag-solo agoric open --repl

You should see:

Launching wallet...
http://127.0.0.1:8000#accessToken=kIqLZ99mQe6TGpvTN...

Visit that URL to open the Agoric wallet and REPL.

Right away the wallet should show "connected" to the local ag-solo, but most of the page is inactive while it does a few on-chain transactions to locate issuers and such. Then you should see a few purses with balances of various (fictitious) tokens.

Persistent state: the ag-solo volume

You may have noticed that the ag-solo service generated a key when it started:

ag-solo_1  | 2021-03-23T19:50:25.466Z ag-solo: init: key generated, now extracting address

The docker-compose.yml file is configured to set up an ag-solo docker volume to store that key and your client state.

You can bring your ag-solo service up and down as usual; the ag-solo volume is preserved:

docker-compose down

docker-compose up -d

# to check whether it's up or down:
docker-compose ps

DANGER ZONE

You have two different choices for initializing a new client:

A. If you just want to create a new client then:

1. shut down your ag-solo service as described above. That makes port 8000 available again.
2. create and change to a differently-named directory
3. download the docker-compose.yml into the new directory and continue from there. The different name will mean that the docker containers and state won't conflict with your previous client.

B. On the other hand, if you want to reset the client state (note that this will LOSE ALL ITS TOKENS), use docker-compose down -v to remove the persistent volume.