{"id":13478830,"url":"https://github.com/blinklabs-io/docker-cardano-node","last_synced_at":"2026-05-05T01:08:21.608Z","repository":{"id":57201516,"uuid":"463223627","full_name":"blinklabs-io/docker-cardano-node","owner":"blinklabs-io","description":"Builds Intersect's Haskell cardano-node from source using cabal on debian","archived":false,"fork":false,"pushed_at":"2025-04-18T14:59:50.000Z","size":875,"stargazers_count":29,"open_issues_count":1,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-19T04:19:18.819Z","etag":null,"topics":["cardano","cardano-cli","cardano-node","docker","docker-container","docker-image","dockerfile"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/blinklabs-io.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-02-24T16:39:52.000Z","updated_at":"2025-04-18T14:59:53.000Z","dependencies_parsed_at":"2023-02-16T00:01:05.002Z","dependency_job_id":"8994a892-13ee-4d7c-8d04-eeae81d6725a","html_url":"https://github.com/blinklabs-io/docker-cardano-node","commit_stats":null,"previous_names":[],"tags_count":83,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blinklabs-io%2Fdocker-cardano-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blinklabs-io%2Fdocker-cardano-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blinklabs-io%2Fdocker-cardano-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blinklabs-io%2Fdocker-cardano-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blinklabs-io","download_url":"https://codeload.github.com/blinklabs-io/docker-cardano-node/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251750598,"owners_count":21637749,"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":["cardano","cardano-cli","cardano-node","docker","docker-container","docker-image","dockerfile"],"created_at":"2024-07-31T16:02:04.118Z","updated_at":"2026-05-05T01:08:21.602Z","avatar_url":"https://github.com/blinklabs-io.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# docker-cardano-node\n\nBuilds a Cardano full node from source on Debian. This image attempts to keep\ninterface compatibility with\n[cardano-node](https://github.com/IntersectMBO/cardano-node), but may diverge\nslightly, particularly with any Nix-specific paths.\n\nWe found that the learning curve for using Nix is too high for many in the\ncommunity who need to run a full node for various reasons but don't want to\nget too heavy into learning a new operating system just to extend a container\nimage. This image uses FHS paths and installs into `/usr/local` while taking\nadvantage of multi-stage image builds to reduce final image size over the\nofficial Nix-based distribution.\n\n## Additional Images\n\nThe Dockerfile also exposes build targets for `cardano-tracer` and\n`cardano-submit-api`, reusing the same build artifacts as the full node image.\n\n```bash\ndocker build --target cardano-tracer -t ghcr.io/blinklabs-io/cardano-tracer .\ndocker build --target cardano-submit-api -t ghcr.io/blinklabs-io/cardano-submit-api .\n```\n\nThese targets keep the Cardano executables and supporting libraries while\nomitting the node entrypoint scripts.\n\n## Running a Cardano Node\n\nThe container image has some differing behaviors depending on how it's\ninvoked. There is a `NETWORK` environment variable which can be used as a\nshort cut to starting nodes on a specific named Cardano network with a default\nconfiguration.\n\nWe recommend using this method for running the container if you are not\nfamiliar with running a node.\n\nFor nodes on the `preprod` and `mainnet` networks, the container will start\nfetching the latest Mithril snapshot if an empty data directory is detected.\nThis snapshot will be used to bootstrap the node into an operating state much\nmore rapidly than doing a sync from the beginning of the chain. This behavior\ncan be disabled in the advanced path below.\n\n### Using NETWORK (Recommended)\n\nUsing the `NETWORK` environment variable causes the entrypoint script to use\nthe simplified path. The only configurable option in this path is the\n`NETWORK` environment variable itself.\n\nThis is in keeping with the IOHK image behavior.\n\nTo run a Cardano full node on preprod:\n\n```bash\ndocker run --detach \\\n  --name cardano-node \\\n  -v node-data:/data/db \\\n  -v node-ipc:/ipc \\\n  -e NETWORK=preprod \\\n  -p 3001:3001 \\\n  ghcr.io/blinklabs-io/cardano-node\n```\n\nNode logs can be followed:\n\n```bash\ndocker logs -f cardano-node\n```\n\nThe node can be monitoring using [nview](https://github.com/blinklabs-io/nview)\nfrom within the container. We run `nview` from within the same container as\nour running node to get access to information about the node process.\n\n```bash\ndocker exec -ti cardano-node nview\n```\n\n#### Running the Cardano CLI\n\nTo run a Cardano CLI command, we use the `node-ipc` volume from our node.\n\n```bash\ndocker run --rm -ti \\\n  -e NETWORK=preprod \\\n  -v node-ipc:/ipc \\\n  ghcr.io/blinklabs-io/cardano-node cli \u003ccommand\u003e\n```\n\nThis can be added to a shell alias:\n\n```bash\nalias cardano-cli=\"docker run --rm -ti \\\n  -e NETWORK=preprod \\\n  -v node-ipc:/ipc \\\n  ghcr.io/blinklabs-io/cardano-node cli\"\n```\n\nNow, you can use cardano-cli commands as you would, normally.\n\n```bash\ncardano-cli query tip --network-magic 1\n```\n\nOr, for a node running with NETWORK=mainnet:\n\n```bash\ncardano-cli query tip --mainnet\n```\n\n### Using run (Recommended for SPO/Advanced)\n\nUsing the `run` argument to the image causes the entrypoint script to use the\nfully configurable code path. Do not set the `NETWORK` environment variable.\n\nTo run a Cardano full node on mainnet with minimal configuration and defaults:\n\nCardano Node before 10.3.1:\n\n```bash\ndocker run --detach \\\n  --name cardano-node \\\n  -v node-data:/opt/cardano/data \\\n  -v node-ipc:/opt/cardano/ipc \\\n  -p 3001:3001 \\\n  ghcr.io/blinklabs-io/cardano-node run\n```\n\n**NOTE** The container paths for persist disks are different in this mode\n\nCardano Node 10.3.1 and above:\n\n```bash\ndocker run --detach \\\n  --name cardano-node \\\n  -v node-data:/data/db \\\n  -v node-ipc:/ipc \\\n  -p 3001:3001 \\\n  ghcr.io/blinklabs-io/cardano-node run\n```\n\nThe above maps port 3001 on the host to 3001 on the container, suitable\nfor use as a mainnet relay node. We use docker volumes for our persistent data\nstorage and IPC (interprocess communication) so they live beyond the lifetime\nof the container. To mount local host paths instead of using Docker's built in\nvolumes, use the local path on the left side of a `-v` argument.\n\nAn example of a more advanced configuration, running a block producer for\nmainnet:\n\n```bash\ndocker run --detach \\\n  --name cardano-node \\\n  --restart unless-stopped \\\n  -e CARDANO_BLOCK_PRODUCER=true \\\n  -e CARDANO_SHELLEY_KES_KEY=/opt/cardano/config/keys/kes.skey \\\n  -e CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE=/opt/cardano/config/keys/node.cert \\\n  -e CARDANO_SHELLEY_VRF_KEY=/opt/cardano/config/keys/vrf.skey \\\n  -v /srv/cardano/node-keys:/opt/cardano/config/keys \\\n  -v /srv/cardano/node-db:/data/db \\\n  -v /srv/cardano/node-ipc:/ipc \\\n  -p 3001:3001 \\\n  -p 12798:12798 \\\n  ghcr.io/blinklabs-io/cardano-node run\n```\n\n##### Dynamic Block Forging\n\nTo start a block producer in non-producing mode initially (for dynamic block forging):\n\n```bash\ndocker run --detach \\\n  --name cardano-node \\\n  --restart unless-stopped \\\n  -e CARDANO_BLOCK_PRODUCER=true \\\n  -e START_AS_NON_PRODUCING=true \\\n  -e CARDANO_SHELLEY_KES_KEY=/opt/cardano/config/keys/kes.skey \\\n  -e CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE=/opt/cardano/config/keys/node.cert \\\n  -e CARDANO_SHELLEY_VRF_KEY=/opt/cardano/config/keys/vrf.skey \\\n  -v /srv/cardano/node-keys:/opt/cardano/config/keys \\\n  -v /srv/cardano/node-db:/data/db \\\n  -v /srv/cardano/node-ipc:/ipc \\\n  -p 3001:3001 \\\n  -p 12798:12798 \\\n  ghcr.io/blinklabs-io/cardano-node run\n```\n\nWith dynamic block forging enabled, you can control block production without restarting the node:\n\n- **Enable block forging**: Ensure credential files are present and send SIGHUP\n\n  ```bash\n  docker exec cardano-node pkill -SIGHUP cardano-node\n  ```\n\n- **Disable block forging**: Move/rename credential files and send SIGHUP\n\n  ```bash\n  docker exec cardano-node mv /opt/cardano/config/keys/kes.skey /opt/cardano/config/keys/kes.skey.disabled\n  docker exec cardano-node pkill -SIGHUP cardano-node\n  ```\n\n- **Re-enable block forging**: Restore credential files and send SIGHUP\n\n  ```bash\n  docker exec cardano-node mv /opt/cardano/config/keys/kes.skey.disabled /opt/cardano/config/keys/kes.skey\n  docker exec cardano-node pkill -SIGHUP cardano-node\n  ```\n\nThe above uses Docker's built in supervisor to restart a container which fails\nfor any reason. This will also cause the container to automatically restart\nafter a host reboot, so long as Docker is configured to start on boot. We\nset variables to configure a block producer and pass the paths to the 3 keys\nwe need. Our node's persistent data and client communication socket are mapped\nto `/srv/cardano/node-db` and `/srv/cardano/node-ipc` on the host,\nrespectively. This allows for running applications directly on the host which\nmay need access to these. We also map `/srv/cardano/node-keys` on the host to\na path within the container to support running as a block producer. Last, we\nadd mapping the host's port 12798 to the container 12798, which is the port for\nexposing the node's metrics in Prometheus format, for monitoring.\n\nThis mode of operation allows configuring multiple facets of the node using\nenvironment variables, described below.\n\nNode logs can be followed:\n\n```bash\ndocker logs -f -n 500 cardano-node\n```\n\nAdding the `-n 500` to the logs command limits the logs to the last 500 lines\nbefore following.\n\n#### Configuration using environment variables\n\nThe power in using `run` is being able to configure the node's behavior to\nprovide the correct type of service.\n\nThis behavior can be changed via the following environment variables:\n\n- `CARDANO_CONFIG_BASE`\n  - A directory which contains configuration files (default:\n    `/opt/cardano/config`)\n  - This variable is used as the base for other configuration variable default\n- `CARDANO_BIND_ADDR`\n  - IP address to bind for listening (default: `0.0.0.0`)\n- `CARDANO_BLOCK_PRODUCER`\n  - Set to true for a block producing node (default: false)\n  - Requires key files and node certificates to be present to start\n- `CARDANO_CONFIG`\n  - Full path to the Cardano node configuration (default:\n    `${CARDANO_CONFIG_BASE}/mainnet/config.json`)\n  - Use your own configuration file to modify the node behavior fully\n- `CARDANO_DATABASE_PATH`\n  - A directory which contains the ledger database files (default:\n    `/data/db`)\n  - This is the location for persistent data storage for the ledger\n- `CARDANO_PORT`\n  - TCP port to bind for listening (default: `3001`)\n- `CARDANO_RTS_OPTS`\n  - Controls the Cardano node's Haskell runtime (default:\n    `-N2 -A64m -I0 -qg -qb --disable-delayed-os-memory-return`)\n  - This allows tuning the node for specific use cases or resource contraints\n- `CARDANO_SOCKET_PATH`\n  - UNIX socket path for listening (default: `/ipc/node.socket`)\n  - This socket speaks Ouroboros NtC and is used by client software\n- `CARDANO_TOPOLOGY`\n  - Full path to the Cardano node topology (default:\n    `${CARDANO_CONFIG_BASE}/mainnet/topology.json`)\n\n#### Running a block producer\n\nTo run a block producing node, you should, at minimum, configure your topology\nto recommended settings and have only your own relays listed. You will need to\nset `CARDANO_BLOCK_PRODUCER` to `true` and provide the appropriate key files\nand operational certificate.\n\n- `CARDANO_SHELLEY_KES_KEY`\n  - Stake pool hot key, authenticates (default:\n    `${CARDANO_CONFIG_BASE}/keys/kes.skey`)\n- `CARDANO_SHELLEY_VRF_KEY`\n  - Stake pool signing key, verifies (default:\n    `${CARDANO_CONFIG_BASE}/keys/vrf.skey`)\n- `CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE`\n  - Stake pool identity certificate (default:\n    `${CARDANO_CONFIG_BASE}/keys/node.cert`)\n- `START_AS_NON_PRODUCING`\n  - Start block producer node in non-producing mode (default: `false`)\n  - When set to `true`, adds the `--start-as-non-producing-node` flag\n  - Only applies when `CARDANO_BLOCK_PRODUCER=true`\n  - Enables dynamic block forging control via SIGHUP signals\n\n#### Controlling Mithril snapshots\n\nIf the container does not find a protocolMagicId file within the\n`CARDANO_DATABASE_PATH` location, it will initiate Mithril snapshot downloads\nfor preprod and mainnet networks. This can be disabled by setting\n`RESTORE_SNAPSHOT` to `false`.\n\n- `AGGREGATOR_ENDPOINT`\n  - Mithril Aggregator URL (default:\n    `https://aggregator.release-${CARDANO_NETWORK}.api.mithril.network/aggregator`)\n- `GENESIS_VERIFICATION_KEY`\n  - Network specific Genesis Verification Key (default:\n    `reads file at: ${CARDANO_CONFIG_BASE}/${CARDANO_NETWORK}/genesis.vkey`)\n- `SNAPSHOT_DIGEST`\n  - Digest identifier to fetch (default: `latest`)\n\n#### Running the Cardano CLI\n\nTo run a Cardano CLI command, we use the `node-ipc` volume from our node.\n\n```bash\ndocker run --rm -ti \\\n  -v node-ipc:/ipc \\\n  ghcr.io/blinklabs-io/cardano-node cli \u003ccommand\u003e\n```\n\nThis can be added to a shell alias:\n\n```bash\nalias cardano-cli=\"docker run --rm -ti \\\n  -v node-ipc:/ipc \\\n  ghcr.io/blinklabs-io/cardano-node cli\"\n```\n\nNow, you can use cardano-cli commands as you would, normally.\n\n```bash\ncardano-cli query tip --mainnet\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblinklabs-io%2Fdocker-cardano-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblinklabs-io%2Fdocker-cardano-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblinklabs-io%2Fdocker-cardano-node/lists"}