Docker

All XChain services run as Docker containers managed by the xchain-node CLI. This document covers container naming, networking, volume management, and common Docker operations.

Container Naming Convention

Containers follow a predictable naming scheme based on the service, coin, and network:

Coin-specific services:

xchain-node-<coin>-<network>-<service>

Examples:

• xchain-node-bitcoin-mainnet-xchain-decoder
• xchain-node-litecoin-regtest-xchain-indexer
• xchain-node-dogecoin-mainnet-xchain-utxo-tracker

Shared services (no coin/network scope):

xchain-node-<service>

Examples:

• xchain-node-xchain-hub
• xchain-node-xchain-explorer
• xchain-node-database

This naming is consistent across docker ps, docker logs, and the xchain-node CLI.

Docker Networks

Each coin+network stack gets its own Docker network for service isolation:

xchain-node-<coin>-<network>

Examples:

• xchain-node-bitcoin-mainnet
• xchain-node-litecoin-regtest

A base network named xchain-node connects the shared services (hub, explorer, MariaDB).

Containers on the same Docker network can reach each other by container name. For example, the decoder container can reach the MariaDB container at the hostname xchain-node-database.

Creating the network manually (if needed):

docker network create xchain_network

xchain-node creates networks automatically during install, but this may be needed when running explorer via Docker Compose directly.

Environment Variables

Configuration is passed to each container as environment variables. These are set by xchain-node during install based on:

1. Hardcoded defaults in xchain-node/src/index.js
2. Per-chain overrides in xchain-node/config/<coin>-<network> files

Key variables passed to most services:

See Configuration for the full per-service variable reference.

Volume Management

Blockchain Data

Coin nodes store blockchain data in Docker volumes. Volume names follow the container naming convention. Data persists across container restarts and updates.

To list all Docker volumes used by XChain services:

docker volume ls | grep xchain

LevelDB Data

The UTXO tracker uses LevelDB stored in a Docker volume:

• UTXO tracker: /data/xchain-utxo-tracker/ inside the container

The hub uses MariaDB (the shared MariaDB container) for all its data — it does not use LevelDB or Docker volumes for data storage.

MariaDB Data

MariaDB data is stored in its own Docker volume. All decoder and indexer databases for all chains share the single MariaDB container.

Bootstrap Archives

The UTXO tracker supports bootstrap snapshots stored at /bootstrap/xchain-utxo-tracker/ inside the container. xchain-node manages downloading and restoring these via:

xchain-node bootstrap restore xchain-utxo-tracker bitcoin mainnet
xchain-node bootstrap create xchain-utxo-tracker bitcoin mainnet

Viewing Container Logs

Using xchain-node (recommended):

xchain-node logs xchain-decoder bitcoin mainnet
xchain-node tail xchain-decoder bitcoin mainnet

Using Docker directly:

docker logs xchain-node-bitcoin-mainnet-xchain-decoder
docker logs -f xchain-node-bitcoin-mainnet-xchain-decoder
docker logs --tail 100 xchain-node-bitcoin-mainnet-xchain-decoder

For all services at once via the interactive monitor:

xchain-node monitor
xchain-node -i     # full interactive TUI mode

Entering Containers for Debugging

Open a shell inside a running container:

xchain-node shell xchain-decoder bitcoin mainnet
# or directly:
docker exec -it xchain-node-bitcoin-mainnet-xchain-decoder /bin/bash

Run a one-off command:

xchain-node exec xchain-decoder bitcoin mainnet "node --version"
docker exec xchain-node-bitcoin-mainnet-xchain-decoder node --version

Restarting Containers

Via xchain-node:

xchain-node restart xchain-decoder bitcoin mainnet
xchain-node restart all bitcoin mainnet

Via Docker directly:

docker restart xchain-node-bitcoin-mainnet-xchain-decoder

A restart does not wipe data. Services resume from their last processed state.

Updating Containers

xchain-node handles updates by pulling the latest source for the specified branch, rebuilding the Docker image, and replacing the running container:

xchain-node update xchain-decoder bitcoin mainnet
xchain-node update all bitcoin mainnet

The hub is updated automatically as part of every preCheck() call. For explicit hub updates:

xchain-node update xchain-hub

See Upgrading for safe upgrade procedures including database migrations.

Docker Resource Recommendations

MariaDB benefits significantly from RAM (buffer pool size). If the MariaDB container is consuming excessive RAM, tune innodb_buffer_pool_size in the MariaDB configuration.

Backup Strategies

MariaDB

Dump all XChain databases with mysqldump:

docker exec xchain-node-database mysqldump -u root \
  --databases XChain_BTC_Mainnet_Decoder XChain_BTC_Mainnet_Indexer \
  > xchain-backup-$(date +%Y%m%d).sql

LevelDB Volumes

Use the built-in bootstrap mechanism to create compressed snapshots:

xchain-node bootstrap create xchain-utxo-tracker bitcoin mainnet

For the hub, back up the XChain_Hub MariaDB database:

docker exec xchain-node-database mysqldump -u root XChain_Hub \
  > hub-backup-$(date +%Y%m%d).sql

Blockchain Data

Coin node blockchain data can be backed up by stopping the node and copying its Docker volume. However, for mainnet Bitcoin this is rarely practical — it is faster to resync from scratch than to copy hundreds of gigabytes.

Copyright © 2025–2026 Dankest, LLC

Based on XChain Platform by Dankest, LLC – https://dankest.llc

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later) with a commercial license available for proprietary use.

You may use, modify, and distribute this material under the terms of the License. See LICENSE and NOTICE for full terms. See the licensing overview.