Docker Deployment

This guide covers deploying TALER Blockchain nodes using Docker and Docker Compose.

Prerequisites

Before you begin, ensure you have:

Docker: Version 20.10 or higher (Install Docker)
Docker Compose: Version 2.0 or higher (included with Docker Desktop)
Disk Space: At least 20GB for full node
RAM: Minimum 2GB available memory (4GB+ recommended)

Verify installation:

docker --version
docker compose version

Quick Start

Using Docker Compose

The TALER Blockchain repository includes a production-ready docker-compose.yml file.

docker-compose.yml:

services:
  taler:
    image: ghcr.io/abkvme/taler:latest
    container_name: taler-node
    restart: unless-stopped

    ports:
      - "23153:23153"  # P2P network port
      - "23333:23333"  # RPC port

    volumes:
      - taler-data:/data  # Or use host path: ./data:/data
      # - ./taler.conf:/taler.conf:ro  # Uncomment to use custom config file
      # - ./wallet:/wallet  # Uncomment to enable wallet (also set TALER_WALLETDIR=/wallet in .env)

    # Healthcheck disabled by default (requires RPC to be enabled via custom taler.conf)
    # healthcheck:
    #   test: ["CMD", "taler-cli", "getblockchaininfo"]
    #   interval: 60s
    #   timeout: 30s
    #   retries: 5
    #   start_period: 1800s

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  taler-data:
    driver: local

Start the Node

# Start in background
docker compose up -d

# View logs
docker compose logs -f

# Check status
docker compose ps

# Stop the node
docker compose down

Configuration

Default Behavior

By default, the TALER Blockchain Docker container:

Runs without RPC server enabled (security)
Disables wallet functionality
Stores blockchain data in /data volume
Exposes P2P port 23153 and RPC port 23333

Using Custom Configuration File

To enable RPC or customize node behavior, create a taler.conf file:

taler.conf:

# Network settings
listen=1
maxconnections=128

# RPC settings
server=1
rpcuser=yourusername
rpcpassword=your_strong_password_here
rpcport=23333
rpcallowip=0.0.0.0/0
rpcbind=0.0.0.0

# Performance
dbcache=1024
maxmempool=300

# Logging
printtoconsole=1

Uncomment the config volume mount in docker-compose.yml:

volumes:
  - taler-data:/data
  - ./taler.conf:/taler.conf:ro  # Uncomment this line

Restart the container:

docker compose down
docker compose up -d

Enabling Wallet

To enable wallet functionality:

Create a wallet directory:
```
mkdir wallet
```

Uncomment the wallet volume in docker-compose.yml:

volumes:
  - taler-data:/data
  - ./wallet:/wallet  # Uncomment this line

Set the wallet directory environment variable:

environment:
  - TALER_WALLETDIR=/wallet

Restart:

docker compose down
docker compose up -d

Environment Variables

The entrypoint script supports these environment variables:

Variable	Description	Default
`TALER_DATA`	Blockchain data directory	`/data`
`TALER_CONF`	Configuration file path	`/taler.conf`
`TALER_WALLETDIR`	Wallet directory (enables wallet if set)	unset (wallet disabled)

Using Docker Run

Instead of Docker Compose, you can run directly with docker run:

docker run -d \
  --name taler-node \
  -p 23153:23153 \
  -p 23333:23333 \
  -v taler-data:/data \
  ghcr.io/abkvme/taler:latest

With Custom Config

docker run -d \
  --name taler-node \
  -p 23153:23153 \
  -p 23333:23333 \
  -v taler-data:/data \
  -v $(pwd)/taler.conf:/taler.conf:ro \
  ghcr.io/abkvme/taler:latest

With Wallet Enabled

docker run -d \
  --name taler-node \
  -p 23153:23153 \
  -p 23333:23333 \
  -v taler-data:/data \
  -v $(pwd)/wallet:/wallet \
  -e TALER_WALLETDIR=/wallet \
  ghcr.io/abkvme/taler:latest

Monitoring and Management

View Logs

# Follow logs
docker compose logs -f

# Last 100 lines
docker compose logs --tail 100

# Logs for specific service
docker logs taler-node

Execute Commands

# Get node info (requires RPC enabled)
docker exec taler-node taler-cli getinfo

# Get blockchain info
docker exec taler-node taler-cli getblockchaininfo

# Get connection count
docker exec taler-node taler-cli getconnectioncount

Access Container Shell

docker exec -it taler-node /bin/bash

Container Stats

# Real-time stats
docker stats taler-node

# One-time snapshot
docker stats --no-stream taler-node

Volume Management

Inspect Volume

docker volume inspect taler-data

Backup Blockchain Data

# Create backup
docker run --rm \
  -v taler-data:/data \
  -v $(pwd):/backup \
  ubuntu tar czf /backup/taler-backup-$(date +%Y%m%d).tar.gz /data

Restore Backup

docker run --rm \
  -v taler-data:/data \
  -v $(pwd):/backup \
  ubuntu tar xzf /backup/taler-backup-YYYYMMDD.tar.gz -C /

Using Host Directory

Instead of Docker volume, use a host directory:

volumes:
  - ./data:/data  # Host directory

This stores blockchain data in ./data on your host system.

Building Custom Image

The TALER Blockchain repository includes a Dockerfile for building custom images.

Build Locally

# Clone repository
git clone https://github.com/abkvme/taler.git
cd taler

# Build image
docker build -t taler:local .

# Run local build
docker run -d \
  --name taler-node \
  -p 23153:23153 \
  -v taler-data:/data \
  taler:local

Multi-Architecture Build

The Dockerfile supports both linux/amd64 and linux/arm64:

# Build for multiple platforms
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t taler:custom \
  .

Healthcheck Configuration

To enable health monitoring, ensure RPC is enabled in your taler.conf, then uncomment the healthcheck section in docker-compose.yml:

healthcheck:
  test: ["CMD", "taler-cli", "getblockchaininfo"]
  interval: 60s
  timeout: 30s
  retries: 5
  start_period: 1800s  # 30 minutes for initial sync

Check health status:

docker inspect --format='{{.State.Health.Status}}' taler-node

Security Best Practices

RPC Port Binding

For security, bind RPC port to localhost only when possible:

ports:
  - "23153:23153"
  - "127.0.0.1:23333:23333"  # Localhost only

Strong RPC Credentials

Generate strong passwords:

openssl rand -base64 32

File Permissions

Protect your configuration file:

chmod 600 taler.conf

Keep Images Updated

Regularly update to the latest image:

docker compose pull
docker compose up -d

Running in Rootless Mode

If you run Docker in rootless mode, the default rootlesskit port forwarder can silently fail to expose the TALER P2P port 23153 on the host. The container starts normally and docker compose ps shows the port mapping, but no incoming peer connections arrive and getconnectioncount stays at 0.

The fix is a one-time global Docker user-service override that switches the rootless network/port driver to pasta (a modern, faster replacement for slirp4netns).

1. Install `pasta`

pasta ships with the passt package and is not preinstalled on most distros. Install it system-wide:

# Debian / Ubuntu
sudo apt install passt

# Fedora / RHEL / CentOS Stream
sudo dnf install passt

# Arch / Manjaro
sudo pacman -S passt

# openSUSE
sudo zypper install passt

Verify the binary is on PATH:

pasta --version

2. Create the override

Edit (or create) ~/.config/systemd/user/docker.service.d/override.conf:

[Service]
Environment=DOCKERD_ROOTLESS_ROOTLESSKIT_NET=pasta

3. Reload and restart the rootless Docker daemon

systemctl --user daemon-reload
systemctl --user restart docker

4. Restart the TALER container

docker compose down
docker compose up -d

After this, the published P2P port 23153 is reachable from the host and remote peers, and the node accepts inbound connections normally. No changes to docker-compose.yml or taler.conf are required.

This setting applies only to rootless Docker. Standard (rootful) Docker installations do not need it.

Troubleshooting

Container Won’t Start

# Check logs for errors
docker compose logs

# Check container status
docker compose ps -a

# Remove and recreate
docker compose down
docker compose up -d

RPC Connection Issues

If taler-cli commands fail:

Ensure RPC is enabled in taler.conf with server=1
Verify config file is mounted: docker exec taler-node ls -la /taler.conf
Check if RPC credentials are correct

Blockchain Sync Issues

# Check sync progress
docker exec taler-node taler-cli getblockchaininfo

# View debug output in logs
docker compose logs -f

Reset Blockchain Data

# Stop container
docker compose down

# Remove volume (WARNING: deletes all blockchain data)
docker volume rm taler-data

# Restart
docker compose up -d

Production Deployment

Run as System Service

Create /etc/systemd/system/taler-docker.service:

[Unit]
Description=TALER Blockchain Docker Node
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/taler
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable taler-docker
sudo systemctl start taler-docker

Automatic Updates

Use Watchtower to auto-update containers:

services:
  taler:
    # ... existing config ...

  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 86400  # Check daily

Next Steps

Node CLI: Learn command-line operations in Node CLI
Mining & Staking: Configure mining/staking in Mining & Staking
RPC API: Build applications with Developer Documentation

Documentation