docs: add a Quick Start to run Axon and Blockscan Locally with docker…

…-compose

.github/workflows/build_image_ghcr.yml

@@ -22,54 +22,95 @@ jobs:
       packages: write
 
     steps:
-      - uses: actions/checkout@v3
-        with:
-          ref: ${{ github.event.inputs.commit_sha || '' }}
+    - uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.inputs.commit_sha || '' }}
 
-      # Extract metadata (tags, labels) for the Docker image
-      # https://github.com/docker/metadata-action
-      - name: Extract Docker metadata
-        id: meta
-        uses: docker/metadata-action@v4
-        with:
-          images: ${{ env.REGISTRY }}${{ github.repository_owner }}/${{ env.IMAGE_NAME }}
-          flavor: |
-            latest=auto
-          tags: |
-            type=ref,event=tag
-            type=semver,pattern={{version}}
-            type=ref,event=branch
-            # minimal (short sha)
-            type=sha,enable=true,prefix=sha-,format=short
-      - name: Echo steps.meta.outputs.bake-file
-        run: cat ${{ steps.meta.outputs.bake-file }}
+    # Extract metadata (tags, labels) for the Docker image
+    # https://github.com/docker/metadata-action
+    - name: Extract Docker metadata
+      id: meta
+      uses: docker/metadata-action@v4
+      with:
+        images: ${{ env.REGISTRY }}${{ github.repository_owner }}/${{ env.IMAGE_NAME }}
+        flavor: |
+          latest=auto
+        tags: |
+          type=ref,event=tag
+          type=semver,pattern={{version}}
+          type=ref,event=branch
+          # minimal (short sha)
+          type=sha,enable=true,prefix=sha-,format=short
+    - name: Echo steps.meta.outputs.bake-file
+      run: cat ${{ steps.meta.outputs.bake-file }}
 
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v2
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
+    - name: Set up QEMU
+      uses: docker/setup-qemu-action@v2
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v2
 
-      - name: Login to Github resgistry
-        uses: docker/login-action@v2
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Build and push image to ${{ env.REGISTRY }}${{ github.repository_owner }}/${{ env.IMAGE_NAME }}
-        uses: docker/build-push-action@v4
-        with:
-          context: .
-          file: ./Dockerfile
-          platforms: linux/amd64
-          push: ${{ github.event_name != 'pull_request' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
+    - name: Login to Github resgistry
+      uses: docker/login-action@v2
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.repository_owner }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+    - name: Build and push image to ${{ env.REGISTRY }}${{ github.repository_owner }}/${{ env.IMAGE_NAME }}
+      uses: docker/build-push-action@v4
+      with:
+        context: .
+        file: ./Dockerfile
+        platforms: linux/amd64
+        push: ${{ github.event_name != 'pull_request' }}
+        tags: ${{ steps.meta.outputs.tags }}
+        labels: ${{ steps.meta.outputs.labels }}
 
-      - name: Check versions of the binaries in ${{ fromJSON(steps.meta.outputs.json).tags[0] }}
-        if: ${{ github.event_name != 'pull_request' }}
-        env:
-          IMAGE: ${{ fromJSON(steps.meta.outputs.json).tags[0] }}
-        run: |
-          docker run --rm ${{ env.IMAGE }} /app/axon --version
+    - name: Check versions of the binaries in ${{ fromJSON(steps.meta.outputs.json).tags[0] }}
+      if: ${{ github.event_name != 'pull_request' }}
+      env:
+        IMAGE: ${{ fromJSON(steps.meta.outputs.json).tags[0] }}
+      run: |
+        docker run --rm ${{ env.IMAGE }} /app/axon --version
 
-    # TODO: test the image
+    - name: Record image info to the outputs of this job
+      id: result
+      run: |
+        echo "image_name=`echo ${{ fromJSON(steps.meta.outputs.json).tags[0] }} | awk -F ':' '{print $1}'`" >> $GITHUB_OUTPUT
+        echo "image_tag=`echo ${{ fromJSON(steps.meta.outputs.json).tags[0] }} | awk -F ':' '{print $NF}'`" >> $GITHUB_OUTPUT
+
+    # Map the meta step outputs to this job outputs
+    outputs:
+      image_name: ${{ steps.result.outputs.image_name }}
+      image_tag: ${{ steps.result.outputs.image_tag }}
+
+  test-in-docker-compose:
+    needs: build-amd64-image-to-ghcr
+    runs-on: ubuntu-22.04
+    defaults:
+      run:
+        working-directory: devtools/chain
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Modify Axon image
+      env:
+        AXON_IMAGE: "${{ needs.build-amd64-image-to-ghcr.outputs.image_name }}:${{ needs.build-amd64-image-to-ghcr.outputs.image_tag }}"
+      uses: mikefarah/yq@v4
+      with:
+        cmd: |
+          echo "Update the image of Axon"
+          yq -i '.services.axon.image = "${{ env.AXON_IMAGE }}"' ./docker-compose.yml
+          echo "====== devtools/chain/docker-compose.yml ======"
+          cat docker-compose.yml
+
+    - name: Run docker compose up and a simple test
+      run: |
+        docker-compose up -d
+        docker-compose ps
+        docker-compose logs --tail 6
+
+        npx zx <<'EOF'
+        import { waitXBlocksPassed } from '../ci/scripts/helper.js'
+        await waitXBlocksPassed('http://127.0.0.1:8000', 2);
+        EOF

devtools/chain/README.md

@@ -1,8 +1,77 @@
- # The meaning of each transactions in Genesis.json
- 1. `nonce = 0` means: Creation of metadata implementation contract
- 2. `nonce = 1` means: Creation of wckb contract
- 3. `nonce = 2` means: Creation of metadata proxy contract
- 4. `nonce = 3` means: Creation of crosschain implementation contract
- 5. `nonce = 4` means: Transaction of metadata update
- 6. `nonce = 5` means: Creation of crosschain proxy contract
- 7. `nonce = 6` means: Transaction of wckb grants role to crosschain
+# Quick Start: Running Axon and Blockscan Locally with Docker
+
+Run Axon and it's explorer ([blockscan](https://github.com/Magickbase/blockscan)) locally in Docker containers using [docker-compose](https://github.com/docker/compose). Please read [the `docker-compose` file](./docker-compose.yml) to learn more about the services:
+
+- Axon node
+- Blockscan as the explorer of Axon
+- Postgres database
+
+**Note**: This integration is not production ready.
+
+## Prerequisites
+Before getting started, ensure that you have the following prerequisites installed on your system:
+
+- Docker v20.10+
+- Docker-compose 2.x.x+
+
+## Run the Services
+
+```bash
+git clone --depth=1 https://github.com/axonweb3/axon.git
+cd axon/devtools/chain
+docker-compose up -d
+
+
+```
+
+### Watch the logs
+To monitor the logs of the running services, use the following command:
+```bash
+docker-compose logs -f --tail 1
+```
+
+This command will display the logs of the services, showing the latest log entries.
+```js
+chain-axon-1  | [2023-08-25T08:45:29.751879179+00:00 INFO overlord::state::process] Overlord: achieve consensus in height 254, costs 1 round 4.499679ms time
+postgres      | 2023-08-25 08:43:02.542 UTC [28] LOG:  checkpoint complete: wrote 134 buffers (0.8%); 0 WAL file(s) added, 0 removed, 0 recycled; write=13.325 s, sync=0.003 s, total=13.336 s; sync files=34, longest=0.003 s, average=0.001 s; distance=966 kB, estimate=966 kB
+blockscan     | 2023-08-25T08:45:24.008 application=indexer fetcher=empty_blocks_to_refetch [info] Start sanitizing of empty blocks. Batch size is 100
+...
+```
+
+### Access the Chain
+Use [Etheruem JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc) to interact with the Axon node. For instance, to get the chain ID of the Axon devnet, execute the following cURL command:
+```bash
+# Get the chain ID of the Axon devnet
+curl --location --request POST 'http://127.0.0.1:8000' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{
+    "id": 42,
+    "jsonrpc": "2.0",
+    "method": "eth_chainId",
+    "params": []
+}'
+
+# Result: a JSON response containing the chain ID of the Axon devnet.
+{"jsonrpc":"2.0","result":"0x7e6","id":42}
+```
+
+### Accessing [Blockscan](http://127.0.0.1:4020)
+To access the Blockscan explorer, open your browser and visit http://127.0.0.1:4020. This will allow you to explore the Axon blockchain using the Blockscan interface.
+![Blockscan](blockscan-screenshot.png)
+
+## You are good to go!
+Congratulations! 
+You have successfully set up and run Axon and Blockscan locally in Docker containers. You can now start exploring the Axon blockchain and interacting with the services.
+
+Next Steps: [Deploy and Interact with a Solidity Contract](https://docs.axonweb3.io/getting-started/for-dapp-devs/deploy_solidity)
+
+
+<!--
+docs: update the meaning of each transactions in Genesis.json
+TODO: https://github.com/axonweb3/axon/issues/1276
+
+# The meaning of each transactions in Genesis.json
+1. `nonce = 0` means: Creation of metadata implementation contract
+2. `nonce = 1` means: Creation of wckb contract
+3. `nonce = 2` means: Creation of metadata proxy contract
+-->

devtools/chain/blockscan-explorer.env

@@ -0,0 +1,110 @@
+# Configuration variables of blockscan
+#
+# More configs, please refer to:
+# 1. https://github.com/Magickbase/blockscan/tree/main/docker-compose/envs
+# 2. https://github.com/Magickbase/blockscan/blob/main/dev.env
+# 3. https://github.com/Magickbase/blockscan/blob/main/dev-local.env
+#
+# Descriptions of the ENVs are available in
+# https://docs.blockscout.com/for-developers/information-and-settings/env-variables
+
+DATABASE_URL=postgresql://blockscan:b%rnGL8ps@explorer-db:5432/blockscan?ssl=false
+
+
+NETWORK=Axon
+SUBNETWORK=AxonChain
+ETHEREUM_JSONRPC_HTTP_URL=http://axon:8000
+ETHEREUM_JSONRPC_TRACE_URL=http://axon:8000
+ETHEREUM_JSONRPC_TRANSPORT=http
+# ETHEREUM_JSONRPC_WS_URL=
+
+
+# TODO: update Axon's logo
+LOGO=/images/blockscout_logo.svg
+LOGO_FOOTER=/images/blockscout_logo.svg
+
+
+# TODO: Simplify the configs, maybe we could get rid of the default configs from here?
+# cc @Simon-Tl
+IPC_PATH=
+NETWORK_PATH=/
+API_PATH=/
+SOCKET_ROOT=/
+BLOCKSCOUT_HOST=
+BLOCKSCOUT_PROTOCOL=
+PORT=4020
+EMISSION_FORMAT=DEFAULT
+POOL_SIZE=40
+POOL_SIZE_API=10
+ECTO_USE_SSL=false
+HEART_BEAT_TIMEOUT=30
+BLOCKSCOUT_VERSION=
+RELEASE_LINK=
+BLOCK_TRANSFORMER=axon
+LINK_TO_OTHER_EXPLORERS=false
+OTHER_EXPLORERS={}
+SUPPORTED_CHAINS={}
+CACHE_BLOCK_COUNT_PERIOD=7200
+CACHE_TXS_COUNT_PERIOD=7200
+CACHE_ADDRESS_COUNT_PERIOD=7200
+CACHE_ADDRESS_SUM_PERIOD=3600
+CACHE_TOTAL_GAS_USAGE_PERIOD=3600
+CACHE_ADDRESS_TRANSACTIONS_GAS_USAGE_COUNTER_PERIOD=1800
+CACHE_TOKEN_HOLDERS_COUNTER_PERIOD=3600
+CACHE_TOKEN_TRANSFERS_COUNTER_PERIOD=3600
+CACHE_ADDRESS_WITH_BALANCES_UPDATE_INTERVAL=1800
+CACHE_AVERAGE_BLOCK_PERIOD=1800
+CACHE_MARKET_HISTORY_PERIOD=21600
+CACHE_ADDRESS_TRANSACTIONS_PERIOD=1800
+CACHE_ADDRESS_TOKENS_USD_SUM_PERIOD=1800
+CACHE_ADDRESS_TOKEN_TRANSFERS_COUNTER_PERIOD=1800
+CACHE_BRIDGE_MARKET_CAP_UPDATE_INTERVAL=1800
+CACHE_TOKEN_EXCHANGE_RATE_PERIOD=1800
+TOKEN_METADATA_UPDATE_INTERVAL=172800
+ALLOWED_EVM_VERSIONS=homestead,tangerineWhistle,spuriousDragon,byzantium,constantinople,petersburg,istanbul,berlin,london,default
+UNCLES_IN_AVERAGE_BLOCK_TIME=false
+DISABLE_WEBAPP=false
+DISABLE_READ_API=false
+DISABLE_WRITE_API=false
+DISABLE_INDEXER=false
+INDEXER_DISABLE_PENDING_TRANSACTIONS_FETCHER=true
+INDEXER_DISABLE_INTERNAL_TRANSACTIONS_FETCHER=true
+WOBSERVER_ENABLED=false
+SHOW_ADDRESS_MARKETCAP_PERCENTAGE=true
+CHECKSUM_ADDRESS_HASHES=true
+CHECKSUM_FUNCTION=eth
+DISABLE_EXCHANGE_RATES=true
+DISABLE_KNOWN_TOKENS=true
+ENABLE_TXS_STATS=true
+SHOW_PRICE_CHART=false
+SHOW_TXS_CHART=true
+HISTORY_FETCH_INTERVAL=30
+TXS_HISTORIAN_INIT_LAG=0
+TXS_STATS_DAYS_TO_COMPILE_AT_INIT=10
+COIN_BALANCE_HISTORY_DAYS=90
+APPS_MENU=true
+EXTERNAL_APPS=[]
+DISABLE_BRIDGE_MARKET_CAP_UPDATER=true
+INDEXER_DISABLE_BLOCK_REWARD_FETCHER=true
+ENABLE_POS_STAKING_IN_MENU=false
+SHOW_MAINTENANCE_ALERT=false
+MAINTENANCE_ALERT_MESSAGE=
+SHOW_STAKING_WARNING=false
+STAKING_WARNING_MESSAGE=
+CUSTOM_CONTRACT_ADDRESSES_TEST_TOKEN=
+ENABLE_SOURCIFY_INTEGRATION=false
+SOURCIFY_SERVER_URL=
+SOURCIFY_REPO_URL=
+MAX_SIZE_UNLESS_HIDE_ARRAY=50
+HIDE_BLOCK_MINER=false
+DISPLAY_TOKEN_ICONS=false
+SHOW_TENDERLY_LINK=false
+TENDERLY_CHAIN_PATH=
+MAX_STRING_LENGTH_WITHOUT_TRIMMING=2040
+RE_CAPTCHA_SECRET_KEY=
+RE_CAPTCHA_CLIENT_KEY=
+API_RATE_LIMIT=50
+API_RATE_LIMIT_BY_KEY=50
+API_RATE_LIMIT_BY_IP=50
+API_RATE_LIMIT_WHITELISTED_IPS=
+API_RATE_LIMIT_STATIC_API_KEY=

devtools/chain/docker-compose.yml

@@ -0,0 +1,51 @@
+version: '3.8'
+
+services:
+  axon:
+    # TODO: update this image to ghcr.io/axonweb3/axon:dev
+    image: ghcr.io/flouse/axon:dev
+    ports:
+    - 8000:8000
+    - 127.0.0.1:8100:8100
+    volumes:
+    - ./config.toml:/app/config.toml
+    - ./default.db-options:/app/default.db-options
+    - ./specs/single_node/:/app/single_node_spec/
+    networks:
+    - axon-net
+    restart: unless-stopped
+    command: |
+      /app/axon run --config=/app/config.toml --chain-spec=/app/single_node_spec/chain-spec.toml
+
+  explorer:
+    container_name: blockscan
+    # TODO: update blockscan image
+    # Dockerfile: https://github.com/Simon-Tl/blockscan/blob/a60dd45ca8577f97683f89c8a372508a84b74e24/docker/Dockerfile#L56
+    image: ghcr.io/simon-tl/blockscan:latest
+    depends_on:
+    - axon
+    - explorer-db
+    env_file:
+    - ./blockscan-explorer.env
+    ports:
+    - 4020
+    networks:
+    - axon-net
+    restart: unless-stopped
+    command: bash -c "bin/blockscout eval \"Elixir.Explorer.ReleaseTasks.create_and_migrate()\" && bin/blockscout start"
+
+  explorer-db:
+    container_name: postgres
+    image: postgres:15.2
+    environment:
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-b%rnGL8ps}
+      POSTGRES_USER: ${POSTGRES_USER:-blockscan}
+    expose:
+    - 5432
+    networks:
+    - axon-net
+    restart: unless-stopped
+    command: postgres -c 'max_connections=250'
+
+networks:
+  axon-net: