{"id":43847577,"url":"https://github.com/xray-network/xray-graph-koios-tiny","last_synced_at":"2026-02-06T06:10:43.088Z","repository":{"id":166354648,"uuid":"635384663","full_name":"xray-network/xray-graph-koios-tiny","owner":"xray-network","description":"XRAY/Graph Koios Tiny — Dockerized Koios (Cardano-Db-Sync) stack","archived":false,"fork":false,"pushed_at":"2026-01-23T08:30:40.000Z","size":255,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-24T01:19:57.821Z","etag":null,"topics":["api","cardano","cardano-db-sync","indexer","koios","xray"],"latest_commit_sha":null,"homepage":"https://xray.app","language":"PLpgSQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xray-network.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-05-02T15:22:23.000Z","updated_at":"2026-01-23T08:25:52.000Z","dependencies_parsed_at":"2024-02-26T13:30:56.604Z","dependency_job_id":"49abd538-5105-4a26-bac7-15d367fba1d8","html_url":"https://github.com/xray-network/xray-graph-koios-tiny","commit_stats":null,"previous_names":["ray-network/xray-graph-output","xray-network/xray-graph-output","xray-network/xray-graph-koios-tiny"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/xray-network/xray-graph-koios-tiny","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xray-network%2Fxray-graph-koios-tiny","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xray-network%2Fxray-graph-koios-tiny/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xray-network%2Fxray-graph-koios-tiny/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xray-network%2Fxray-graph-koios-tiny/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xray-network","download_url":"https://codeload.github.com/xray-network/xray-graph-koios-tiny/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xray-network%2Fxray-graph-koios-tiny/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29153283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T02:39:25.012Z","status":"ssl_error","status_checked_at":"2026-02-06T02:37:22.784Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","cardano","cardano-db-sync","indexer","koios","xray"],"created_at":"2026-02-06T06:10:39.861Z","updated_at":"2026-02-06T06:10:43.083Z","avatar_url":"https://github.com/xray-network.png","language":"PLpgSQL","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca href=\"https://discord.gg/WhZmm46APN\"\u003e\u003cimg alt=\"Discord\" src=\"https://img.shields.io/discord/852538978946383893?style=for-the-badge\u0026logo=discord\u0026label=Discord\u0026labelColor=%231940ED\u0026color=%233FCB9B\"\u003e\u003c/a\u003e\n\n# XRAY/Graph Koios Tiny — Dockerized Koios (Cardano-Db-Sync)\n\nXRAY/Graph Koios Tiny is a tool for fast and predictable deployment of [Koios](https://koios.rest/) (Cardano-Db-Sync) stack in a docker environment. Used in the [XRAY/Graph](https://xray.app/) distributed Cardano API provider.\n\n## Getting Started\n\n### Prepare Installation\n\n``` console\ngit clone \\\n  --recurse-submodules \\\n  https://github.com/xray-network/xray-graph-koios-tiny.git \\\n  \u0026\u0026 cd xray-graph-koios-tiny\n```\n  \n### MAINNET\n\n``` console\nNETWORK=mainnet \\\nPOSTGRES_PASSWORD=your_secret_password \\\ndocker compose -f docker-compose.yaml -p koios-tiny-mainnet up -d --build\n```\n  \n### PREPROD\n\n``` console\nNETWORK=preprod \\\nPOSTGRES_PASSWORD=your_secret_password \\\nPOSTGRES_PORT=5433 \\\nOGMIOS_PORT=1338 \\\nCARDANO_PORT=3001 \\\nKOIOS_PORT=8051 \\\nOGMIOS_PROXY_PORT=8701 \\\nRAPIDOC_KOIOS_PORT=2701 \\\ndocker compose -f docker-compose.yaml -p koios-tiny-preprod up -d --build\n```\n\n\u003c/details\u003e\n  \n### PREVIEW\n\n``` console\nNETWORK=preview \\\nPOSTGRES_PASSWORD=your_secret_password \\\nPOSTGRES_PORT=5434 \\\nOGMIOS_PORT=1339 \\\nCARDANO_PORT=3002 \\\nKOIOS_PORT=8052 \\\nOGMIOS_PROXY_PORT=8702 \\\nRAPIDOC_KOIOS_PORT=2702 \\\ndocker compose -f docker-compose.yaml -p koios-tiny-preview up -d --build\n```\n\n## Advanced Usage\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eRestoring From Snapshot\u003c/b\u003e\u003c/summary\u003e\n  \n## Step 0: Installing Dependencies\n\nInstalling dependepcies (if needed):\n``` console\nsudo apt update \u0026\u0026 sudo apt install zstd jq wget -y\n```\n\n## Step 1: Restoring Koios (cardano-db-sync) DB\n\n1. Enter root dir:\n``` console\ncd xray-graph-koios-tiny\n```\n\n2. Download snapshot:\n``` console\nwget 'https://share.koios.rest/api/public/dl/xFdZDfM4/dbsync/mainnet-dbsyncsnap-latest.tgz' -O ./snapshot/mainnet-dbsyncsnap-latest.tgz\n```\n\n3. Run docker compose up (clean run):\n``` console\nRESTORE_SNAPSHOT=/snapshots/mainnet-dbsyncsnap-latest.tgz \\\nNETWORK=mainnet \\\nPOSTGRES_PASSWORD=your_secret_password \\\ndocker compose -f docker-compose.yaml -p koios-tiny-mainnet up -d --build\n```\n\n## Step 2: Restoring Cardano Node DB\n\n1. Enter root dir:\n``` console\ncd xray-graph-koios-tiny\n```\n\n2. Stop cardano-node-ogmios container:\n``` console\ndocker stop *container_id*\n```\n\n3. Download lates cardano-node-ogmios db:\n``` console\nwget -c -O - \"https://downloads.csnapshots.io/mainnet/$(wget -qO- https://downloads.csnapshots.io/mainnet/mainnet-db-snapshot.json | jq -r .[].file_name)\" | zstd -d -c | tar -x -C ./snapshots\n```\n\n4. Get node_db volume id:\n``` console\ndocker volume ls\n```\n\n5. Remove cardano-node-ogmios db and copy downloaded:\n```\nsudo rm -rf /var/lib/docker/volumes/*cardano-node-ogmios_node_db-volume-id*/_data \\\nsudo mv ./snapshots/db /var/lib/docker/volumes/*cardano-node-ogmios_node_db-volume-id*/_data\n```\n\n6. Start cardano-node-ogmios container:\n\n``` console\ndocker start *container_id*\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eAPI Status Check\u003c/b\u003e\u003c/summary\u003e\n\nRaw CURL query examples:\n  \n``` console\ncurl 0.0.0.0:8050/rpc/tip\n```\n``` console\ncurl 0.0.0.0:8050/rpc/blocks\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eTypeScript Client\u003c/b\u003e\u003c/summary\u003e\n  \nWe recommend to use `cardano-koios-client`. Visit [cardano-koios-client](https://github.com/xray-network/cardano-koios-client) repo for more information.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003ePostgresql Config\u003c/b\u003e\u003c/summary\u003e\n  \nConfig files (see end of file): \n\n- mainnet: config/postgresql/postgresql.mainnet.conf\n- preprod: config/postgresql/postgresql.preprod.conf\n- preview: config/postgresql/postgresql.preview.conf\n\nUse https://pgtune.leopard.in.ua/ to tune the database settings\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eUpdating Git Submodules\u003c/b\u003e\u003c/summary\u003e\n\nIf you are upgrading a version, you may have to upgrade all the submodule dependencies\n\n``` console\ngit submodule update --recursive --remote --merge\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eKoios Custom RPCs \u0026 Cron Tasks\u003c/b\u003e\u003c/summary\u003e\n  \nPlace the `.sql` files in the `koios/extra-rpc` folder to register with Postgrest. Place the .sh files in `koios/extra-cron-jobs` and edit the `koios/cron-schedule`.\n\nThen you must rebuild container with `--force-rebuild` command.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eUsing in Graph Cluster (Traefik Reverse Proxy)\u003c/b\u003e\u003c/summary\u003e\n\n1. Clone and run Traefik:\n``` console\ngit clone https://github.com/xray-network/traefik-docker.git \\\n\u0026\u0026 cd traefik-docker \\\n\u0026\u0026 docker compose up -d\n```\n\n2. Set `BEARER_RESOLVER_TOKEN` and `docker-compose.xray.yaml`:\n``` console\nNETWORK=mainnet \\\nPOSTGRES_PASSWORD=your_secret_password \\\nBEARER_RESOLVER_TOKEN=your_access_token \\\ndocker compose -f docker-compose.xray.yaml -p koios-tiny-mainnet up -d --build\n```\n\n\u003c/details\u003e\n\n## Documentation\n\n* Koios Rapidoc Playground (OpenAPI Schema) — https://graph.xray.app/output/services/koios/mainnet/api/v1/\n* Koios OpenAPI Schema (JSON) — https://graph.xray.app/output/services/koios/mainnet/api/v1/openapi.json\n* Koios TypeScript Client — https://github.com/xray-network/cardano-koios-client\n* Original Koios — https://koios.rest/\n* Original Koios OpenAPI Schema — https://api.koios.rest/\n* Cardano-Db-Sync — https://github.com/IntersectMBO/cardano-db-sync/\n* Ogmios — https://ogmios.dev/\n* Traefik — https://traefik.io/traefik\n\n\n## System Requirements\n  \nIn general, this stack loads the system in the same way as `cardano-db-sync`, so the minimal system requirements will be the same:\n\n* Any of the big well known Linux distributions (eg, Debian, Ubuntu, RHEL, CentOS, Arch etc).\n* 64 Gigabytes of RAM or more.\n* 4 CPU cores or more.\n* 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.\n* Minimum 1000 Gigabytes or more of SSD disk storage.\n  \nWhen 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).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxray-network%2Fxray-graph-koios-tiny","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxray-network%2Fxray-graph-koios-tiny","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxray-network%2Fxray-graph-koios-tiny/lists"}