{"id":39178196,"url":"https://github.com/bisgardo/concordium-docker","last_synced_at":"2026-01-17T22:30:41.309Z","repository":{"id":37746155,"uuid":"381144098","full_name":"bisgardo/concordium-docker","owner":"bisgardo","description":"A collection of scripts and configuration files to build and deploy a containerized node for the Concordium blockchain.","archived":false,"fork":false,"pushed_at":"2025-05-27T09:57:35.000Z","size":381,"stargazers_count":5,"open_issues_count":23,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-27T10:44:16.968Z","etag":null,"topics":["concordium","docker","docker-compose","helm-chart"],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bisgardo.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}},"created_at":"2021-06-28T19:44:12.000Z","updated_at":"2024-12-30T10:25:11.000Z","dependencies_parsed_at":"2023-02-11T07:30:40.464Z","dependency_job_id":"e44beb12-8f13-4301-bac5-049503662eb2","html_url":"https://github.com/bisgardo/concordium-docker","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/bisgardo/concordium-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bisgardo%2Fconcordium-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bisgardo%2Fconcordium-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bisgardo%2Fconcordium-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bisgardo%2Fconcordium-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bisgardo","download_url":"https://codeload.github.com/bisgardo/concordium-docker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bisgardo%2Fconcordium-docker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28520642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T22:11:28.393Z","status":"ssl_error","status_checked_at":"2026-01-17T22:11:27.841Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["concordium","docker","docker-compose","helm-chart"],"created_at":"2026-01-17T22:30:41.241Z","updated_at":"2026-01-17T22:30:41.290Z","avatar_url":"https://github.com/bisgardo.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# concordium-docker\n\nA collection of scripts and configuration files to build and deploy a containerized,\ndynamically linked node for the [Concordium](https://concordium.com) blockchain.\n\n## Quickstart\n\nStart a Concordium Node deployment with name `\u003cnode-name\u003e`\nusing Docker Compose with [pre-built images](#ci-public-images):\n\n*Testnet*\n\n```shell\nNODE_NAME=\u003cnode-name\u003e ./run.sh testnet\n```\n\n*Mainnet*\n\n```shell\nNODE_NAME=\u003cnode-name\u003e ./run.sh mainnet\n```\n\n### Additional Features\n\nThe default deployment is minimal; consisting only of a node and collector.\nInstances of additional services and configurations are available as \"features\" that may be enabled individually.\n\nTo enable a given feature, append `+` followed by the name of the feature to the command above.\n\nThe following features are available:\n\n- [Prometheus](#metrics) (metrics): `+prometheus`\n- [Transaction Logger](#transaction-logging): `+txlog`\n- [Rosetta](#rosetta): `+rosetta`\n- [CCDScan](#ccdscan): `+ccdscan`\n\n*Example*\n\nRun a node with name `\u003cnode-name\u003e` and connected instances of Prometheus and Transaction Logger on network `\u003cnetwork\u003e`:\n\n```shell\nNODE_NAME=\u003cnode-name\u003e ./run.sh \u003cnetwork\u003e +prometheus +txlog\n```\n\n## Build\n\nBy default, the builds run in images based on Debian Bullseye (11).\nThe build arg `debian_release` may be used to select another Debian release,\nthough no other than the default value should be expected to work.\n\n### `concordium-node`\n\nDual-purpose Docker image containing the applications `concordium-node` and `node-collector`\n(for reporting state to the public [dashboard](https://dashboard.mainnet.concordium.software)).\nThe two applications are intended to run in separate containers instantiated from this image.\n\nThe image may be build with Docker using the following command or using Docker Compose as described below:\n\n```shell\ndocker build -t concordium-node:\u003ctag\u003e --build-arg=tag=\u003ctag\u003e .\n```\n\nwhere `\u003ctag\u003e` is the desired commit tag from the\n[`concordium-node`](https://github.com/Concordium/concordium-node) code repository.\nThe tag is also used for the resulting Docker image.\n\nIf a branch name is used for `\u003ctag\u003e` (not recommended),\nthen the `--no-cache` flag should be set to prevent the Docker daemon from using a\npreviously cached clone of the source code at an older version of the branch.\n\nThe latest tag may be found in the [official repository](https://github.com/Concordium/concordium-node/tags).\nHowever, the tags don't always match the currently deployed software versions on both networks.\n\nYou may also check the tags of the [public images](#ci-public-images) (the part before `_`)\nto see what Concordium Node tag was used in the latest build (and which networks' .env files have been updated to use it).\nHowever, this repo not being updated regularly, so this information is prone to being outdated.\n\n*Optional*\n\nThe versions of external tools used in the build are defined as the default values of build arguments.\nThis is mostly done to keep them in one place as a set of constants, but also means that they can be overriden at build time.\nSee the top of the dockerfile for the available set of args.\n\n### `concordium-node-genesis`\n\nMicro image that holds a genesis data file for the purpose of copying it into the node container on startup.\n\nThis was originally the preferred method of injecting the file,\nbut the node now allows its location to be configurable,\nallowing it to be passed as a simple bind mount.\n\nTo this end, the following genesis files are located in directory [`genesis`](./genesis):\n\n- `mainnet-0.dat`: Initial genesis data for Mainnet (started on 2021-06-09; [source](https://distribution.mainnet.concordium.software/data/genesis.dat)).\n- `testnet-1.dat`: Genesis data for Testnet (started on 2022-06-13; [source](https://distribution.testnet.concordium.com/data/genesis.dat)).\n\nThe directory also holds the now-unused dockerfile for the genesis image. See commit `17dde7d` for the old instructions.\n\n## Build and/or run using Docker Compose\n\nThe project includes a full Docker Compose (v2) deployment for running a node and collector,\noptionally along with a set of related services (each of which is enabled individually).\nInstructions on how to install the Compose plugin are given in the [official documentation](https://docs.docker.com/compose/install/).\n\nThe project has been tested with Compose v2.20.2.\n\nThe main setup is configured in [`docker-compose.yaml`](./docker-compose.yaml)\nand is thoroughly parameterized to work with any Concordium blockchain network (including unofficial ones).\n\nTo build and run a node/collector instance on Mainnet with Prometheus enabled, adjust and run the following command:\n\n```shell\nNODE_NAME=my_node \\\nNODE_TAG=\u003ctag\u003e \\\nDOMAIN=mainnet.concordium.software \\\nGENESIS_DATA_FILE=./genesis/mainnet-0.dat \\\nNODE_IMAGE=concordium-node:\u003ctag\u003e \\\nCOMPOSE_PROFILES=prometheus \\\ndocker compose --project-name=mainnet up\n```\n\nwhere `\u003ctag\u003e` is as described above.\n\nThe variable `NODE_NAME` sets the name to be displayed on [CCDScan](https://ccdscan.io/nodes).\n\nThe variable `DOMAIN` determines which concrete network to join.\nThe publicly available official options are:\n\n- `mainnet.concordium.software`\n- `testnet.concordium.com`\n\nDefining the variable `CONCORDIUM_NODE_LOG_LEVEL_DEBUG` (with any value) enables debug logging for the node.\n\nThe node collector starts up with a default delay of 30s to avoid filling the log with query errors until the node is ready.\nThis may be overridden with the variable `NODE_COLLECTOR_DELAY_MS` which takes the delay in milliseconds.\nThe service restarts automatically if it crashes due to too many unsuccessful connection attempts.\n\nBy default the node collector uses gRPC APIv2 (on port 11000).\nTo support running older images, this value may be overridden using the variable `NODE_COLLECTOR_PORT`.\n\nAdding `--project-name=\u003cname\u003e` to `docker compose up` prepends `\u003cname\u003e` to the names of containers and other persistent resources,\nmaking it possible to switch between networks without having to delete data and existing containers.\nNote that because ports are fixed, running multiple nodes at the same time is not supported with the current setup.\n\nThe command will automatically build the images from scratch if they don't already exist.\nSet the flag `--no-build` to prevent that.\nTo only build the images without starting containers, use the command `... docker compose build`,\nwhich also supports the option `--build-arg` to override build args in the compose file.\nSee the [Compose CLI reference](https://docs.docker.com/compose/reference/)\nfor the full list of commands and arguments.\n\nRunning a node without Docker Compose or some other orchestration tool is cumbersome but of course possible:\n[Look up](https://docs.docker.com/compose/compose-file/compose-file-v3/) the features used in the Compose file\nand [find](https://docs.docker.com/engine/reference/commandline/run/) the corresponding `docker run` args.\n\nThe deployment may be stopped using `Ctrl-C` (unless running in detached mode) or `docker compose stop`.\nIn the latter case, make sure to pass all the same project name, environment variables, etc. as were given to `up`.\nIn both cases, the default behavior is to send a SIGTERM signal to the running containers with a\n[10 sec deadline](https://docs.docker.com/compose/faq/#why-do-my-services-take-10-seconds-to-recreate-or-stop)\nfor the containers to stop.\nOnce the deadline has passed, the containers are killed with SIGKILL.\nIn certain cases (like on startup), the node may need more than a few seconds to terminate gracefully.\nIt's therefore good practice to increase this deadline using e.g.\n\n```shell\ndocker compose stop --timeout=120\n```\n\nAn even safer option is to only send it a SIGTERM signal:\n\n```shell\ndocker kill --signal=SIGTERM \u003ccontainer\u003e\n```\n\nStopping the node during OOB catchup (see below) is not recommended\nas it's been seen to cause internal data corruption in the past.\n\n### Out-of-band (OOB) catchup\n\nWhen the node needs to catch up a large number of blocks (like when it's starting from scratch),\nit may minimize its network activity by importing blocks \"out-of-band\".\n\nThe Concordium Foundation publishes archived chunks of blocks once per day for Mainnet and Testnet.\nThe feature for downloading and ingesting these archives is enabled by default.\n\nWhile running in catchup mode, the node will not have any peers.\n\nThe OOB feature used to be implemented in a way that required the user\nto download one big archive in advance of starting the node.\nThe new mode is supported by recent node versions only.\nSupport for the old mode was removed from this project in commit `bdd0731`.\n\n### Metrics\n\nThe node exposes a few metrics as a [Prometheus](https://prometheus.io) scrape endpoint on port `9090`.\nIf profile `prometheus` is enabled, a Prometheus [instance](https://hub.docker.com/r/prom/prometheus)\nthat is configured to scrape itself and the node is started as well.\nSee [prometheus.yml](./metrics/prometheus.yml) for the configuration.\nThe web UI of that service is exposed to the host on port `9009`.\n\nThe Prometheus server may also serve as a Grafana data source for powering advanced dashboards.\nSee this project's [metrics documentation](./metrics/README.md) for details.\n\n### Backing up persisted data\n\nData in a persisted volume may be mounted into a throwaway container and backed up from there,\nfor instance by archiving it into a bind mount.\n\nThe data compresses well with LZMA (usually uses `.xz` extension).\nThe dockerfile `backup.Dockerfile` builds an image that supports that format:\n\n```shell\ndocker build -f ./backup.Dockerfile -t concordium-backup --pull .\n```\n\nAs an example, the following command archives the contents of a volume `data` into a file `./backup/data.tar.xz` located in a bind mount:\n\n```shell\ndocker run --rm --volume=data:/mnt/data --volume=\"${PWD}/backup\":/mnt/backup --workdir=/mnt concordium-backup tar -Jcf ./backup/data.tar.xz ./data\n```\n\nRestoring the backup at `./backup/data.tar.xz` into a fresh (or properly wiped) volume `data`\nis then just a matter of extracting instead of creating:\n\n```shell\ndocker run --rm --volume=data:/mnt/data --volume=\"${PWD}\"/backup:/mnt/backup --workdir=/mnt concordium-backup tar -xf ./backup/data.tar.xz\n```\n\n## Usage\n\nRun the following command to get a list of supported arguments:\n\n```shell\ndocker run --rm concordium-node:\u003ctag\u003e /concordium-node --help | less\n```\n\n## Transaction logging\n\nThe Concordium Node used to include the ability to log transactions to an external PostgreSQL database.\nDue to various shortcomings, this feature has been removed in favor of an equivalent service\n[`concordium-transaction-logger`](https://github.com/Concordium/concordium-transaction-logger).\nThis service is deployed separately, handles errors gracefully,\nand may run against multiple nodes that don't need any particular configuration or state.\nThe DB schemas are documented in the readme of the logger service.\n\nThe Docker Compose file includes a transaction logger service under the profile `txlog`.\nThe [image](https://hub.docker.com/r/concordium/transaction-logger/tags) is specified with the variable `TRANSACTION_LOGGER_IMAGE`.\n\nDatabase credentials etc. are configured with the following variables:\n\n- `TXLOG_PGDATABASE` (default: `concordium_txlog`): Name of the database in the PostgreSQL instance created for the purpose.\n- `TXLOG_PGHOST` (default: `172.17.0.1`): DNS or IP address of the host.\n  The default value assumes that the PostgreSQL instance is running natively, i.e. outside of Docker.\n- `TXLOG_PGPORT` (default: `5432`): Port of the PostgreSQL instance.\n- `TXLOG_PGUSER` (default: `postgres`): Username of the PostgreSQL user used to log the transactions.\n- `TXLOG_PGPASSWORD`: Password of the PostgreSQL user.\n- `TXLOG_QUERY_CONCURRENCY` (default: 4): Number of threads to allocate for querying the node's gRPC interface.\n  This value of this variable only matters when catching up a large number of blocks -\n  setting it to 1 is fine during normal operation.\n\nThe variables may be passed to the `docker compose` command above or persisted in an env file as [described below](#ci-public-images).\nnote that `TXLOG_PGPASSWORD` still has to be passed explicitly).\n\nSee [`postgresql.md`](./postgresql.md) for instructions on how to set up a local database.\n\n## Rosetta\n\nThe Docker Compose file supports running an instance of the [Concordium implementation](https://github.com/Concordium/concordium-rosetta)\nof the [Rosetta](https://www.rosetta-api.org/) API under the profile `rosetta`.\nThe server registers itself on port `8086`.\nThe [image](https://hub.docker.com/r/concordium/rosetta/tags) to deploy is specified with the variable `ROSETTA_IMAGE`.\nTo avoid initial crash-looping until the node is up,\nthe variable `ROSETTA_STARTUP_DELAY_SECS` sets an optional delay (defaults to 1 min) before the service is started.\n\nThe [`network_identifier`](https://github.com/Concordium/concordium-rosetta#identifiers) expected by the instance is\n\n```shell\n{\"blockchain\": \"concordium\", \"network\": \"\u003cproject name\u003e\"}\n```\n\nwhere `\u003cproject name\u003e` is the Compose project name; i.e. the value of `--project-name`\nor the `\u003cnetwork\u003e` parameter of `./run.sh`.\n\nSee the [official documentation](https://github.com/Concordium/concordium-rosetta) of `concordium-rosetta`\nfor more details about this application.\n\n## CCDScan\n\nEnabling the override `ccdscan` activates an instance of CCDScan as part of the deployment.\nThe backend is exposed on port `5000` and the frontend on port `5080`.\nThe frontend is built from a custom dockerfile with a configuration that makes it independent of Firebase.\nThe backend is deployed from an image in the [public repository](https://hub.docker.com/r/concordium/ccdscan/)\nor one [built separately](https://github.com/Concordium/concordium-scan/blob/main/backend/Dockerfile).\n\n## CI: Public images\n\nA GitHub Actions CI job for building and pushing the images to\n[a public registry](https://hub.docker.com/r/bisgardo/concordium-node) is defined in\n[`./.github/workflows/build-push.yaml`](.github/workflows/build-push.yaml).\n\nFor example, a Mainnet node setup that includes a Prometheus instance may be run using the Docker Compose script like so:\n\n```shell\nexport NODE_NAME=my_node\nexport DOMAIN=mainnet.concordium.software\nexport GENESIS_DATA_FILE=./genesis/mainnet-0.dat\nexport NODE_IMAGE=bisgardo/concordium-node:\u003ctag\u003e\ndocker compose pull # prevent 'up' from building instead of pulling\ndocker compose --project-name=mainnet up --profile=prometheus --no-build\n```\n\n*TODO: Make the following its own (sub)section that explains using env files and run.sh in general. Probably belong under the section about building and running with Compose. Remember to update references (to this section) appropriately.*\n\nThe convenience script [`run.sh`](./run.sh) expects to find a file `./\u003cnetwork\u003e.env`\n([`mainnet.env`](./mainnet.env) and [`testnet.env`](./testnet.env) being provided with the repo)\nfrom which it loads the deployment parameters and network-specific values:\n\n```shell\nNODE_NAME=my_node ./run.sh \u003cnetwork\u003e [+\u003cfeature\u003e...]\n```\n\nwhere `\u003cfeature\u003e` is a Compose profile to be enabled and/or an override to be applied ([list](#additional-features)).\n\nAn override `\u003cfeature\u003e` is a file `docker-compose.\u003cfeature\u003e.yaml` which - if it exists - get merged\nonto the \"base\" `docker-compose.yaml` file.\nMultiple profiles/overrides may be enabled by appending a `+` argument for each of them.\nOverrides are applied in the order of the enabling arguments.\n\nThis mechanism provides a flexible way for users to reconfigure and extend the deployment\nby adding their own override files to modify existing services, extend existing profiles, define new profiles, etc.\n\nNote that `run.sh` doesn't follow Compose's\n[default behavior](https://docs.docker.com/compose/extends/#understanding-multiple-compose-files)\nof applying `docker-compose.override.yaml` automatically (it could still be enabled manually with the option `+override`).\n\nUsing `run.sh`, the example above simplifies to\n\n```shell\nNODE_NAME=my_node ./run.sh mainnet +prometheus\n```\n\nTo instead enable [transaction logging](#transaction-logging), append `+txlog` and pass the DB password:\n\n```shell\nTXLOG_PGPASSWORD=\u003cdatabase-password\u003e NODE_NAME=my_node ./run.sh \u003cnetwork\u003e +txlog\n```\n\nThe env files reference the most recently published images,\nwhere the version is compatible with the \"currently active\" tag of the corresponding network\n(as of the time the image was built).\nThe tag of a given image mathes the tag of the git commit that Concordium Node was built from\nfollowed by an additional \"build version\" component (the part after `_`)\nThe build version starts at 0 for any given Node tag and is bumped whenever a new build is pushed for that same tag\n(for example when building with an updated compiler).\n\n### Disclaimer\n\nFeel free to use these images for testing and experimentation,\nbut never trust random internet strangers' pre-built binaries with anything secret or valuable.\n\nInstead, use the\n[officially released](https://developer.concordium.software/en/mainnet/net/guides/run-node-ubuntu.html)\nbinaries or build them yourself on trusted hardware.\n\nBe sure to completely understand what all build and deployment files that you are using are doing.\nDon't clone this repository in any kind of pipeline to use build anything critical -\nuse your own copy/fork or just take the files that you need.\nBy using any files from this repository,\nyou accept full responsibility of their effect and availability now and in the future,\nso review carefully and only apply changes explicitly.\n\n## Development\n\n### Git pre-commit hook\n\nTo avoid committing incorrectly formatted YAML (and have it rejected by the CI), a git pre-commit hook can verify it before committing:\n\nThe hook is implemented using the [`pre-commit`](https://pre-commit.com/) tool which may be installed using `pip`:\n\n```shell\npip install pre-commit\n```\n\nThe `requirements.txt` file specifies a compatible version.\n\nThen just run `pre-commit install` from the project root to install the hook that's defined in `.pre-commit-config.yaml`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbisgardo%2Fconcordium-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbisgardo%2Fconcordium-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbisgardo%2Fconcordium-docker/lists"}