kaspad in Docker

Install Docker

Skip this if docker --version already prints a version.

sudo apt update
sudo apt install -y ca-certificates curl
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

docker --version
docker compose version

Write the compose file

One short file describes the node: which image, which ports, where the data lives.

mkdir -p ~/kaspad-docker
cd ~/kaspad-docker

Save this in that folder as docker-compose.yml:

services:
  kaspad:
    image: kaspanet/rusty-kaspad:latest
    container_name: kaspad
    restart: unless-stopped
    ports:
      - "16111:16111"            # P2P, needed for a public node
      - "127.0.0.1:16110:16110"  # RPC, from this machine only
    volumes:
      - kaspad-data:/app/data
    command:
      - kaspad
      - --yes
      - --nologfiles
      - --disable-upnp
      - --utxoindex
      - --rpclisten=0.0.0.0:16110
    logging:
      options:
        max-size: "50m"
        max-file: "3"

volumes:
  kaspad-data:

restart

Brings the node back after a crash or a reboot

ports

16111 for other nodes; 16110 for RPC, from this machine only

volumes

Chain data that outlives the container

command

Runs kaspad with the index wallets need

logging

Keeps the log to 150 MB

Know where the data lives

The chain is stored in a Docker volume, separate from the container, so upgrades never touch it.

docker volume ls
docker volume inspect kaspad-docker_kaspad-data

Don't delete the volume. Removing kaspad-data throws away the whole chain and the node has to sync again from nothing.

Start the node

The first run downloads the image and creates the volume.

cd ~/kaspad-docker
docker compose up -d
docker compose ps

Check it is syncing

The first sync takes one to two hours on a machine that meets the requirements, longer on slower ones. Follow the log; press Ctrl+C to stop following.

docker compose logs -f kaspad

Make it public

Optional, and the most useful thing you can do: a public node helps new nodes join and sync.

1. Find the local address of the machine running Docker.
2. Open your router's admin page, usually at 192.168.1.1.
3. Forward external TCP port 16111 to that machine, port 16111.

The container doesn't ask the router to open the port, so forward it by hand. On a Linux host with a firewall, open the port there too:

sudo ufw allow 16111/tcp

Router menus differ. portforward.com has steps for most models.

Day-to-day commands

Everything you'll need once it is running.

Stop

Copy

docker compose stop

Start

Copy

docker compose start

Restart

Copy

docker compose restart

Update to the newest version

Copy

docker compose pull
docker compose up -d

Which version is running

Copy

docker compose exec kaspad printenv RUSTY_VERSION

Resource use

Copy

docker stats kaspad

Troubleshooting

The usual problems and what fixes them.