Setting up an Agoric Dapp Client with docker compose

Quick Start (Overview)

0. Install Docker Compose (if you haven't already)
1. Download the latest Devnet Preview Release 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 using the devnet faucet updated 2023-04-20 for agoricdev-17
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 using the devnet faucet

Use https://devnet.faucet.agoric.net/ to register your client. Be sure to choose the IST option and ag-solo.

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

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  | 2022-12-08T20:31:05.892Z chain-cosmos-sdk: gas estimate: ....

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.