Dockerized version of kaspad, the Kaspa Daemon and it's cmdline tools.
- SPDX-FileCopyrightText: © 2022 Kaspa Developers
- SPDX-License-Identifier: ISC
This repository contains some compose files for easy usage of provided Docker images. Additionally the Docker images could be built by yourself using provided Dockerfile and build helper script.
To simple start kaspad as a container, you can use docker-compose-kaspad.yaml
like this:
❯ docker compose -f docker-compose-kaspad.yaml up --detach
This will start kaspad
on a container instance and put all data onto a separate Docker volume. So these data is persistent and will be reused if the container is destroyed/restarted.
To see the logs just use this cmd:
❯ docker compose -f docker-compose-kaspad.yaml logs -f
Exit the log output using Ctrl-C
.
To shutdown the instance properly, you should use this cmd:
❯ docker compose -f docker-compose-kaspad.yaml down
The Docker volume is still existing and will be reused with a subsequent start of the container, even if a completely new instance is spawned. The name of the volume will be created out of the folder name of this Git clone and the defined name on the Docker compose file. So without any further tweaks it should look like this:
❯ docker volume ls
DRIVER VOLUME NAME
...
local docker-kaspad_kaspad1
...
Check the used diskspace:
❯ docker system df -v | grep kaspad1
docker-kaspad_kaspad1 1 8.298GB
- 1st col: Volume name
- 2nd col: Amount of containers, on which this volume is mounted
- 3rd col: Used disk space
Remove volume with docker volume rm <volume-name>
i. e. like this:
❯ docker volume rm docker-kaspad_kaspad1
With the compose file docker-compose-kaspawallet.yaml
it is possible to run kaspad
and kaspawallet
. In detail there will be a container which runs kaspad
and a second one which runs kaspawallet
.
The kaspad
Container is similar to the standalone version from the section before. The kaspawallet
container interacts with the kaspad
container and uses it's own Docker volume to persist data.
To simple start kaspad
and kaspawallet
as a containers, you can use docker-compose-kaspawallet.yaml
like this:
❯ docker compose -f docker-compose-kaspawallet.yaml up --detach
This will start kaspad
in one container instance and kaspawallet
within another one. Each container instance will use it's own Docker volume to persist its data and reuse these volumes if the containers were destroyed/restarted.
To see the logs just use this cmd:
❯ docker compose -f docker-compose-kaspawallet.yaml logs -f
Exit the log output using Ctrl-C
.
Within the log output you will see this line:
kaspawallet | /root/.kaspawallet/kaspa-mainnet/keys.json not found, checking again in 60s
This is because kaspawallet
is not configured at the moment. To do so, you need to enter the container instance using docker exec
and setup kaspawallet as usual. This is a onetime step as all the data is stored on the persistent Docker volume.
Hint: Don't be confused about the weird hostname. It's generated by Docker.
❯ docker exec -it kaspawallet bash
24afcd531c88:/#
24afcd531c88:/# kaspawallet create
Enter password for the key file:
Confirm password:
...
Important: Don't forget to store the seed words using kaspawallet dump-unencrypted-data
!
As soon as the first step (kaspawallet create
) is finished, the log output of the kaspawallet container instance will contain these lines:
kaspawallet | 2023-01-01 19:32:27.520 [INF] KSWD: Listening to TCP on localhost:8082 <-- kaspawallet started
kaspawallet | 2023-01-01 19:32:27.520 [INF] KSWD: Connecting to a node at kaspad... <-- Go ahead and connect to kaspad on the other container instance
kaspad | 2023-01-01 19:32:27.525 [INF] TXMP: RPC Incoming connection from 172.22.0.3:39304 #1 <-- kaspad get incoming connection from kaspawallet
kaspawallet | 2023-01-01 19:32:27.530 [INF] KSWD: Connected, reading keys file ... <-- kaspawallet is connected
kaspawallet | 2023-01-01 19:32:27.530 [INF] KSWD: Read, syncing the wallet... <-- Go ahead an sync
kaspawallet | 2023-01-01 19:32:28.096 [INF] KSWD: Wallet is synced, ready for queries <-- Sync finished, kaspawallet ready to use
Now you can work with the wallet on the cmdline within the Docker container:
❯ docker exec -it kaspawallet bash
24afcd531c88:/#
24afcd531c88:/# kaspawallet balance
Total balance, KAS
24afcd531c88:/#
To build from scratch you can use the helper script buildImages.sh
. This script will perform the following steps:
- Optionally create and run a local Docker registry
- To build multi arch images the usage of a Docker registry is required. So if you want to build pure locally (without pushing to a public registry), a local Registry is started.
- Create a Docker BuildX builder instance
- Build and push Docker images for all supported architectures
- The "build" is a real build. To do so the kaspad Github repository is cloned. After that the latest release tag will be checked out and build. Currently (2023-01-01) this is v0.12.11. The resulting Docker image is based on Alpine Linux and contains the binaries
genkeypair
,kaspactl
,kaspad
,kaspaminer
andkaspawallet
, all installed at/usr/local/bin/
for easy usage. - Supported architectures are currently
linux/arm64/v8
andlinux/amd64
.
- The "build" is a real build. To do so the kaspad Github repository is cloned. After that the latest release tag will be checked out and build. Currently (2023-01-01) this is v0.12.11. The resulting Docker image is based on Alpine Linux and contains the binaries
Here's the help output of the build script:
❯ ./buildImages.sh -h
Helper script to build and push multiarch kaspad Docker image.
Per default a local Docker registry at port 5000 is spawned. To use
hub.docker.io, have a look at options -r and -a below.
Usage: ./buildImages.sh [options]
Options:
-a <account-name>
.. If a remote registry shoule be used (see option -r), you need to
give the corresponding account name. Currently only DockerHub is
supported.
-b <builder_name>
.. Name of Docker builder. Default: kaspa_builder
-f .. Force creation of Docker builder. If already existing, the
builder will be removed and recreated.
-p <platform-list>
.. List of plattforms separated by comma.
Default: linux/arm64/v8,linux/amd64
-r .. Use remote Docker registry. Without this option, a local registry
instance at port 5000 will be spawned.
-t <tag>
.. Image tag to use. Default: latest
-h .. Show this help
❯ ./buildImages.sh
Info : Checking local Docker registry
...
Info : -> Done
Info : Get the image with the following cmd:
Info : docker pull 192.168.248.226:5000/docker-kaspad:latest
Notice the last line on the output, which shows the cmd to pull the image.
Note: The IP there is automatically determined by the build script, used to access the local Docker registry and might be different at your setup. As the local build is using http, you need to activate usage of insecure registries on your Docker configuration and add the local registry explicitly.
Example for Docker Desktop (Windows):
{
"insecure-registries": [
"192.168.248.226:5000"
]
}
After this is configured, docker pull should work as expected:
❯ docker pull 192.168.248.226:5000/docker-kaspad:latest
latest: Pulling from docker-kaspad
...
Status: Downloaded newer image for 192.168.248.226:5000/docker-kaspad:latest
192.168.248.226:5000/docker-kaspad:latest
To build the images using a remote registry, you need to login to that registry, so that the build script is able to push the image layers and all the created metadata:
❯ docker login
Login with your Docker ID to push and pull images from Docker Hub. If you don't have a Docker ID, head over to https://hub.docker.com to create one.
Username: hlxeasy
Password:
Login Succeeded
To push to a remote registry you need to use options -r
and -a
with your DockerHub account name. Example:
❯ ./buildImages.sh -r -a hlxeasy -t 1.0
Info : Checking local Docker registry
...
Info : -> Done
Info : Get the image with the following cmd:
Info : docker pull hlxeasy/docker-kaspad:1.0
Happy Kaspa'ing! :-)