{"id":20834006,"url":"https://github.com/trueblocks/trueblocks-docker","last_synced_at":"2025-12-24T21:52:59.476Z","repository":{"id":37086880,"uuid":"167762980","full_name":"TrueBlocks/trueblocks-docker","owner":"TrueBlocks","description":null,"archived":false,"fork":false,"pushed_at":"2025-01-31T14:25:58.000Z","size":4816,"stargazers_count":39,"open_issues_count":5,"forks_count":17,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-31T15:31:32.371Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TrueBlocks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2019-01-27T02:53:31.000Z","updated_at":"2025-01-31T14:26:02.000Z","dependencies_parsed_at":"2023-11-29T15:29:25.296Z","dependency_job_id":"6983aafa-4430-44d8-871e-f9b89b41566c","html_url":"https://github.com/TrueBlocks/trueblocks-docker","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TrueBlocks%2Ftrueblocks-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TrueBlocks%2Ftrueblocks-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TrueBlocks%2Ftrueblocks-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TrueBlocks%2Ftrueblocks-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TrueBlocks","download_url":"https://codeload.github.com/TrueBlocks/trueblocks-docker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243188203,"owners_count":20250453,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-18T00:17:46.843Z","updated_at":"2025-12-24T21:52:59.448Z","avatar_url":"https://github.com/TrueBlocks.png","language":"Dockerfile","readme":"\u003c!-- markdownlint-disable MD033 MD036 MD041 MD003 MD022 MD024 --\u003e\n\u003ch1\u003eTrueBlocks / Docker Version\u003c/h1\u003e\n\n![GitHub repo size](https://img.shields.io/github/repo-size/TrueBlocks/trueblocks-docker)\n[![GitHub contributors](https://img.shields.io/github/contributors/TrueBlocks/trueblocks-docker)](https://github.com/TrueBlocks/trueblocks-docker/contributors)\n[![GitHub stars](https://img.shields.io/github/stars/TrueBlocks/trueblocks-docker?style%3Dsocial)](https://github.com/TrueBlocks/trueblocks-docker/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/TrueBlocks/trueblocks-docker?style=social)](https://github.com/TrueBlocks/trueblocks-docker/network/members)\n[![Twitter Follow](https://img.shields.io/twitter/follow/trueblocks?style=social)](https://twitter.com/trueblocks)\n\n**Table of Contents**\n\n- [Introduction](#introduction)\n- [Requirements](#requirements)\n- [A note on RPC endpoints](#a-note-on-rpc-endpoints)\n- [Configuration](#configuration)\n- [Running the tool](#running-the-tool)\n  - [Using the API](#using-the-api)\n  - [Using `chifra`](#using-chifra)\n- [The Unchained Index](#the-unchained-index)\n- [Data science](#data-science)\n- [Tutorials and examples](#tutorials-and-examples)\n- [Getting started - quick and dirty](#getting-started---quick-and-dirty)\n- [Troubleshooting](#troubleshooting)\n- [Other](#other)\n\n## Introduction\n\nTrueBlocks is a local-first indexing / data access solution for EVM blockchains. This makes it very useful for data science or as a locally-running backend for your Web 3.0 applications.\n\nThis `docker` repo is intentionally minimal serving as a thin layer over [TrueBlocks Core](https://github.com/TrueBlocks/trueblocks-core). Please see that repo for more information about the Unchained Index, chifra (our command-line tool), and the TrueBlocks data API and SDKs.\n\nThis repo is `alpha` software and comes with no warranty implied or otherwise. Use at your own discretion.\n\n## Requirements\n\n`docker` and `docker-compose-plugin` are required. The latest versions of both are suggested.\n\n**Note:** We use the `Compose Plugin` which uses the `docker compose` syntax *NOT* `Compose Standalone` which uses `docker-compose`.\n\n## A note on RPC endpoints\n\nTrueBlocks works with remote RPC endpoints, but we highly recommended that you run your own RPC. An excellent way on a `dAppNode`.\n\nIf you must use a shared endpoint, it's likely that our scraper will be rate limited. This will cause the scraper to fail. You may dial down the speed of the scraper with the `--sleep` option, but of course, now you've dialed down the speed. Your call.\n\n## Configuration\n\nTo get started, create a file called `.env` in the current folder. An [env.example](env.example) file explaining each setting is provided to help you. Adjust the RPC provider to point to an RPC endpoint.\n\n```[shell]\nTB_SETTINGS_DEFAULTCHAIN=mainnet\nTB_CHAINS_MAINNET_RPCPROVIDER=http://host.docker.internal:8545\nTB_KEYS_ETHERSCAN_APIKEY=\u003cyour-Etherscan-api-key\u003e\nTB_SETTINGS_CACHEPATH=/cache\nTB_SETTINGS_INDEXPATH=/unchained\n```\n\nThe `ETHERSCAN_APIKEY` key is optional, but useful to enable the articulation feature.\n\n## Running the tool\n\n1. Make sure your `.env` file is configured [Configuration](#configuration)\n\n2. Create two folders on your host machine to persist the Unchained Index and binary caches:\n\n    ```shell\n    mkdir -p /Users/user/Data/docker/cache\n    mkdir -p /Users/user/Data/docker/unchained\n    ```\n\n    **Note:** Adjust these paths appropriately for your machine.\n\n3. Replace the `source` paths in `docker-compose.yml` with the paths you just made in step 2.\n\n    ```yml\n    ...\n        volumes:\n          - type: bind\n            source: /Users/user/Data/docker/cache     # \u003c--- REPLACE WITH A VALID PATH\n            target: /cache\n          - type: bind\n            source: /Users/user/Data/docker/unchained # \u003c--- REPLACE WITH A VALID PATH\n            target: /unchained\n    ...\n    ```\n\n4. Run `docker compose up`\n\nLeave this tool running in a separate terminal window. It will start the TrueBlocks API server and the scraper. You should see a note indicating the server URL and the progress of the scraper.\n\n### Using the API\n\nThe above commands start TrueBlocks' [API server](https://trueblocks.io/api/). Leave the server running and open a new terminal window.\n\nUse `curl` to test access to the API. For example, the command\n\n```[shell]\ncurl \"http://localhost:8080/blocks?blocks=1-1000:10\"\n```\n\nwill extract every 10th block between blocks 1 and 1,000.\n\n### Using `chifra`\n\nYou may also use the `chifra` command line tool directly. From the current folder, type:\n\n```[shell]\n./scripts/chifra.sh blocks 1-1000:10\n```\n\nThis will produce the same results as the `curl` command.\n\n```[shell]\n./scripts/chifra.sh --help\n```\n\nwill show all available chifra tools. See the [full documentation](https://trueblocks.io/docs/) for detailed information.\n\n**Pro user tip:**\n\nYou may add the following alias to your shell's init script to make `chifra` available from any command line:\n\n```shell\nalias chifra=\"cd \u003cpath\u003e/\u003cto\u003e/trueblocks-docker ; ./scripts/chifra.sh \"\n```\n\nIf you do this, and wish to also run the `core` directly, it may cause a conflict finding `chifra`.\n\n## The Unchained Index\n\nIn the future, this docker will initialize and maintain [the Unchained Index](https://trueblocks.io/papers/2022/file-format-spec-v0.40.0-beta.pdf). Until then, you must initialize it and maintain it yourself.\n\nBefore doing that, please [read and understand this discussion](https://trueblocks.io/docs/install/get-the-index/). It will have an important impact on how `chifra` works for you.\n\nOnce you've read the above, run one of the following two commands:\n\n```shell\n# If you want to initialize the full index (recommended if you have space), or\n./scripts/chifra.sh init --all\n\n# If you want a minimal index and don't mind slower initial queries\n./scripts/chifra.sh init\n\n# Do not run both commands, chose one or the other\n```\n\nDepending on your connection, the above will take several minutes or as much as several hours.\n\nWhen the initialization finishes, decide if you want to run the `scraper`. The scrape maintains the index to the front of the chain. (Note: if you're exploring older data, this step is optional.)\n\nTo start the scraper, do this only after the `chifra init` command finishes:\n\n```[shell]\n./scripts/chifra.sh scrape\n```\n\nAllow this process to continue running in its own terminal window or `tmux` session. If you stop it, the next time you run `chifra`, you will have to re-run the scraper to catch up to the chain.\n\n## Data science\n\n`chifra` is an excellent data science tool. See a few of our articles ([here](https://trueblocks.io/tags/community/), [here](https://trueblocks.io/tags/trueblocks/), and [here](https://trueblocks.io/tags/recipes/)) for ideas on how to take advantage of this very useful tool.\n\n## Tutorials and examples\n\nThe core repo has many examples on how to use not only the `chifra` command line, but also the `TrueBlocks API` and the `TrueBlocks SDK`. Please see the [core repo](https://github.com/TrueBlocks/trueblocks-core) for more information. Note that all three methods of using TrueBlocks are compatible with each other. Learn once, use many.\n\n## Getting started - quick and dirty\n\nThis alternative method of starting the docker image uses volumes to persist the\nUnchained Index and binary caches. It is a great option if you intend only to\nuse our docker version, if you don't need need the Unchained index files\nexternally to docker, or if you want to quickly try out chifra.\n\n1. Make sure your `.env` file is configured [Configuration](#configuration)\n\n2. Run this command:\n\n```bash\ndocker compose -f docker-compose.yml -f docker-compose.volume-override.yml up\n```\n\n## Troubleshooting\n\n**Could not load RPC**\n\nIf you are running your RPC directly on your host machine (not within a docker container) you may get the message:\n\n```text\nCould not load RPC provider: Post \"http://localhost:8545\": dial tcp 127.0.0.1:8545: connect: connection refused\n```\n\nTo fix this, tell docker to use your host network by adding `network_mode: \"host\"` to the `docker-compose.yml`:\n\n```yml\nvolumes:\n  - type: bind\n    # The source should match the cache folder you made when getting started\n    source: /Users/user/Data/docker/cache\n    target: /cache\n  - type: bind\n    # The source should match the Unchained Index folder you made when getting started\n    source: /Users/user/Data/docker/unchained\n    target: /unchained\nnetwork_mode: \"host\"\n```\n\n**Additional property 'name' is not allowed**\n\nIf you get this message, upgrade to the latest version of docker.\n\n## Other\n\n**Documentation**\n\nSee the TrueBlocks website for the [most recent documentation](https://trueblocks.io/docs/).\n\n**License**\n\nThis software is licensed under [GNU Version 3](https://github.com/TrueBlocks/trueblocks-docker/blob/master/LICENSE).\n\n**Contributing**\n\nWe love contributors. Please see information about our [work flow](https://github.com/TrueBlocks/trueblocks-core/blob/develop/docs/BRANCHING.md) before proceeding.\n\n1. Fork this repository into your own repo.\n2. Create a branch: `git checkout -b \u003cbranch_name\u003e`.\n3. Make changes to your local branch and commit them to your forked repo: `git commit -m '\u003ccommit_message\u003e'`\n4. Push back to the original branch: `git push origin TrueBlocks/trueblocks-docker`\n5. Create the pull request.\n\n**Contact**\n\nIf you have questions, comments, or complaints, please join the discussion on our discord server which is [linked from our website](https://trueblocks.io).\n\n**List of Contributors**\n\nThanks to the following people who have contributed to this project:\n\n- [@tjayrush](https://github.com/tjayrush)\n- [@dszlachta](https://github.com/dszlachta)\n- [@wildmolasses](https://github.com/wildmolasses)\n- [@MysticRyuujin](https://github.com/MysticRyuujin)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrueblocks%2Ftrueblocks-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrueblocks%2Ftrueblocks-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrueblocks%2Ftrueblocks-docker/lists"}