XRAY/Graph Koios Tiny — Dockerized Koios (Cardano-Db-Sync) stack

XRAY/Graph Koios Tiny is a tool for fast and predictable deployment of Haproxy (TCP/HTTP Load Balancer), Koios (Cardano-Db-Sync) stack in a docker environment. Used in the XRAY/Graph distributed Cardano API provider.

Getting Started

Prepare Installation

git clone \
  --recurse-submodules \
  https://github.com/xray-network/xray-graph-koios-tiny.git \
  && cd xray-graph-koios-tiny

cp .env.example .env

Build and Run via Docker Compose

You can combine profiles to run multiple networks on the same machine: docker compose --profile mainnet --profile preprod --profile preview up -d

MAINNET

Clean Install

docker compose --profile mainnet up -d --build

Restore Snapshot

You can find the latest cardano-db-sync snapshot (with the consumed-tx-out flag) in the latest Koios release description: https://github.com/cardano-community/koios-artifacts/releases/latest

curl -O --output-dir ./snapshots https://share.koios.rest/api/public/dl/xFdZDfM4/dbsync/mainnet-dbsyncsnap-latest.tgz \
RESTORE_SNAPSHOT_MAINNET=/snapshots/mainnet-dbsyncsnap-latest.tgz \
docker compose --profile mainnet up -d --build

PREPROD

docker compose --profile preprod up -d --build

PREVIEW

docker compose --profile preview up -d --build

Updating Git Submodules

If you are upgrading a version, you may have to upgrade all the submodule dependencies

git submodule update --recursive --remote --merge

Documentation

• Koios (OpenAPI endpoints list) — https://api.koios.rest/
• Koios — https://koios.rest/
• Cardano-Db-Sync — https://github.com/IntersectMBO/cardano-db-sync/
• Ogmios — https://ogmios.dev/
• Haproxy — https://www.haproxy.org/

API Status Check

Raw CURL query examples:

curl 0.0.0.0:8050/rpc/tip

curl 0.0.0.0:8050/rpc/blocks

TypeScript Client

We recommend to use cardano-koios-client. Visit cardano-koios-client repo for more information.

Advanced Usage

Postgresql Config

Config file (see end of file): postgresql.conf
Use https://pgtune.leopard.in.ua/ to tune the database settings

Koios Custom RPCs & Cron Tasks

Place the .sql files in the koios-tiny/extra-rpc folder to register with Postgrest. Then rebuild the koios-tiny-{network} container. Read more at https://postgrest.org/en/stable/references/api.html

Place the .sh files in koios-tiny/extra-cron-jobs and edit the koios-tiny/cron-schedule. Then rebuild the koios-tiny-{network} container.

Rebuild: docker compose up -d --build --force-recreate koios-tiny-{network}.

System Requirements

In general, this stack loads the system in the same way as cardano-db-sync, so the minimal system requirements will be the same:

• Any of the big well known Linux distributions (eg, Debian, Ubuntu, RHEL, CentOS, Arch etc).
• 64 Gigabytes of RAM or more.
• 4 CPU cores or more.
• Ensure that the machine has sufficient IOPS (Input/Output Operations per Second). Ie it should be 100k IOPS or better. Lower IOPS ratings will result in slower sync times and/or falling behind the chain tip.
• Minimum 1000 Gigabytes or more of SSD disk storage.

When building an application that will be querying the database, remember that for fast queries, low latency disk access is far more important than high throughput (assuming the minimal IOPS above is met).