Running Zeko's Archive Node

This guide explains how to add the archive stack on top of an existing Zeko DA node so you can index and query historical data.

Note: This runbook uses a self-hosted DA node. However, you could also use a publicly available DA node.

Complete Running Zeko's DA Node first. This runbook assumes:

• your da-layer service is already running
• your docker-compose.yaml already contains the da-layer setup from the DA node guide
• your da-layer is reachable in Docker Compose as da-layer:1924

Not covered in this guide:

• generating DA node keys
• exposing the archive services to the internet
• running archive-node-api itself

We will extend the same docker compose file you used for the DA node.

Prerequisites

System Requirements

• Linux or macOS (Windows WSL2 works too)
• enough disk space for PostgreSQL and archive history

Installed Software

• Docker
• a working DA node from Running Zeko's DA Node

Overview

In the diagram above you see:

• Zeko's sequencer sending transactions to da-layer
• the optional archive stack that can index and serve historical data from your DA node

The archive stack adds the following services:

• init-db prepares the archive database schema
• postgres stores indexed history
• archive writes blocks into PostgreSQL
• archive-relay reads from Zeko's sequencer and your da-layer, then forwards data to archive

Volumes/files

Volumes	Files	Purpose
initdb_data		Schema file(s) to bootstrap PostgreSQL
postgresql_data		Persistent storage for PostgreSQL
archive_data		Persistent storage for archive
archive-relay_data		Persistent storage for archive-relay
keys_data	da-layer-sk	Private key of the DA node
keys_data	da-layer-pk	Public key of the DA node (used by sequencer)
da-layer_data		Persistent storage for da-layer

Service Overview

• init-db
• postgres
• archive
• archive-relay
• init-config
• da-layer

Ports Exposed

Service	Port	Description
postgres	5432	Database

---

Bootstrap process

Extend docker-compose.yaml with archive services

• Copy docker-compose.yaml to your project folder.

  Click to expand docker-compose.yaml

  services:
    init-db:
      image: docker.io/zekolabs/zeko:latest
      container_name: init-db
      volumes:
        - initdb_data:/data/initdb
      entrypoint:
        - sh
        - -c
      command: >
        "curl -o /data/initdb/create_schema.sql 'https://raw.githubusercontent.com/zeko-labs/zeko/compatible/src/app/archive/create_schema.sql' &&
         echo 'ALTER DATABASE archive OWNER TO archive;' > /data/initdb/init.sql &&
         echo 'Archive database bootstrap complete' &&
         exit 0"
    init-config:
      image: docker.io/zekolabs/zeko:latest
      container_name: init-config
      working_dir: /data
      volumes:
        - keys_data:/data/keys
      entrypoint:
        - sh
        - -c
      restart: "no"
      command: >
        "while [ ! -f /data/keys/.keys_created ];
          do sleep 2;
        done; exit 0"
    postgres:
      depends_on:
        init-db:
          condition: service_completed_successfully
      image: postgres:16
      container_name: postgres
      environment:
        POSTGRES_DB: archive
        POSTGRES_USER: archive
        POSTGRES_PASSWORD: archive
      volumes:
        - postgresql_data:/var/lib/postgresql/data
        - initdb_data:/docker-entrypoint-initdb.d
      ports:
        - "5432:5432"
      restart: unless-stopped
    da-layer:
      depends_on:
        init-config:
          condition: service_completed_successfully
      image: docker.io/zekolabs/zeko-da:latest
      container_name: da-layer
      ports:
        - "1924:1924"
      environment:
        ZEKO_SIGNATURE_KIND: "testnet"
      entrypoint: bash -c
      command: |
        "export MINA_PRIVATE_KEY=$(cat /keys/da-layer-sk) && \\
        exec zeko-da \\
        run-node \\
        --port 1924 \\
        --db-dir /data/db \\
        --network-id testnet"
      volumes:
        - da-layer_data:/data
        - keys_data:/keys:ro
      restart: always
    archive:
      depends_on:
        postgres:
          condition: service_started
      image: zekolabs/zeko-archive-relay:latest
      container_name: archive
      entrypoint: bash -c
      command: |
        "exec zeko-archive run \\
        --postgres-uri postgres://archive:archive@postgres:5432/archive"
      restart: always
      volumes:
        - archive_data:/data
    archive-relay:
      depends_on:
        archive:
          condition: service_started
        da-layer:
          condition: service_started
      image: zekolabs/zeko-archive-relay:latest
      container_name: archive-relay
      entrypoint: bash -c
      command: |
        "exec zeko-archive-relay \\
        --zeko-uri \"https://testnet.zeko.io/graphql\" \\
        --da-node da-layer:1924 \\
        --network-id testnet \\
        --db-dir /data \\
        --sync-period 30 \\
        --log-level Info \\
        --archive-host archive \\
        --archive-port 3086"
      volumes:
        - archive-relay_data:/data
      restart: always
  
  volumes:
    initdb_data:
    postgresql_data:
    archive_data:
    archive-relay_data:
    da-layer_data:
    keys_data:

• Start all services

  docker compose up -d

If all the steps were performed correctly you have the following:

• da-layer getting data from Zeko's L2
• archive-relay pulling data from da-layer and sending to archive
• archive storing transactions in postgresql
• postgres persisting the indexed history

Synchronizing the data

Synchronizing will take a long time. At the time of writing Zeko L2 testnet has 1 million transactions and would take at least a week to get it synced.

Alternatively you can reach out to Zeko for the latest database or checkpoint archive that you can import in your setup and have a fully synced archive stack much faster.

Access your data

You can access the indexed data by running archive-node-api and configuring it to connect to your archive PostgreSQL database.