feat(docker): dockerized node and appchain-pki network

.dockerignore

@@ -0,0 +1,5 @@
+.git
+.gitignore
+docker/Makefile.appchain
+docker/node/
+docker/*.sh

docker/Makefile

@@ -1,23 +1,14 @@
-# appchain, voting
-pki?=voting
-
 warped?=true
 mixes=3
+auths=3
 gateways=1
 serviceNodes=1
 
-# only used by pki=voting
-auths=3
 UserForwardPayloadLength=30000
 
 distro=alpine
-
-# pki=appchain requires debian (katzenpost alpine docker image does not have bash)
-ifeq ($(pki), appchain)
-	distro = debian
-endif
-
-net_name=mixnet
+net_name=voting_mixnet
+docker_compose_yml=$(net_name)/docker-compose.yml
 sh=$(shell if echo ${distro}|grep -q alpine; then echo sh; else echo bash; fi)
 cache_dir=cache
 log_level=DEBUG
@@ -34,7 +25,6 @@ docker_run_sh=$(docker) run ${docker_args} $(mount_net_name) $(mount_opt) --rm k
 katzenpost_dir?=/tmp/katzenpost.opt
 katzenpost_version?=$(shell grep -E '^	github.com/katzenpost/katzenpost ' ../go.mod | awk '{print $$2}')
 net_dir=$(katzenpost_dir)/docker/$(net_name)
-docker_compose_yml=$(net_dir)/docker-compose.yml
 
 # export variables to the environment for consumption by invoked Makefile(s)
 export
@@ -62,7 +52,7 @@ help:
 	@$(MAKE) -e -C $(katzenpost_dir)/docker $@
 
 .PHONY: custom-binaries
-custom-binaries: $(net_dir)/http_proxy.$(distro) $(net_dir)/pki.$(distro)
+custom-binaries: $(net_dir)/http_proxy.$(distro)
 
 .PHONY: custom-config
 custom-config:
@@ -79,27 +69,6 @@ clone-katzenpost:
 			$(katzenpost_dir); \
 	fi
 
-# this genconfig target is intended to be run within the katzenpost docker container
-# for pki=appchain
-.PHONY: genconfig
-genconfig:
-	cd ../genconfig/cmd/genconfig && go build
-	./genconfig.sh
-
-$(docker_compose_yml): $(distro)_base.stamp | $(net_name) $(cache_dir)
-	@if [ "$(pki)" = "appchain" ]; then \
-		$(docker_run_sh) 'cd /go/opt/docker ; make pki=appchain genconfig'; \
-	else \
-		$(MAKE) -e -C $(katzenpost_dir)/docker $@; \
-	fi
-
-.PHONY: $(distro)_base.stamp
-$(distro)_base.stamp:
-	$(MAKE) -e -C $(katzenpost_dir)/docker $@
-
-$(net_dir)/pki.$(distro): $(katzenpost_dir)/docker/$(distro)_base.stamp $(docker_compose_yml) | $(net_name) $(cache_dir)
-	$(docker_run_sh) 'cd /go/opt/pki ; go build -trimpath -ldflags ${ldflags} && mv pki /$(net_name)/pki.$(distro)'
-
 $(net_dir)/http_proxy.$(distro): $(katzenpost_dir)/docker/$(distro)_base.stamp | $(net_name) $(cache_dir)
 	$(docker_run_sh) 'cd /go/opt/server_plugins/cbor_plugins/http_proxy/cmd/http_proxy ; go build -trimpath -ldflags ${ldflags} && mv http_proxy /$(net_name)/http_proxy.$(distro)'
 	cp ../server_plugins/cbor_plugins/http_proxy/http_proxy_config.toml $(net_dir)/servicenode1/

docker/Makefile.appchain

@@ -0,0 +1,62 @@
+net ?= /tmp/appchain-mixnet
+dir_base := /mixnet
+dir_bin := /opt/zkn
+docker_image ?= zkn/node:latest
+docker_image_agent ?= zkn/agent:latest
+docker := $(shell if which podman|grep -q .; then echo podman; else echo docker; fi)
+docker_user ?= $(shell [ "$(docker)" = "podman" ] && echo 0:0 || echo $${SUDO_UID:-$$(id -u)}:$${SUDO_GID:-$$(id -g)})
+docker_compose ?= DOCKER_USER=$(docker_user) $(shell if which podman|grep -q .; then echo DOCKER_HOST="unix://$$XDG_RUNTIME_DIR/podman/podman.sock"; fi) docker compose
+docker_args := --user ${docker_user}
+docker_run := $(docker) run $(docker_args) --network=host --rm --volume $(shell readlink -f $(net)):$(dir_base)
+
+warped?=true
+num_mixes=3
+num_gateways=1
+num_servicenodes=1
+
+probe_count ?= 1
+
+export
+
+$(net):
+	mkdir -vp $(net)
+
+image: $(net)/image.stamp
+$(net)/image.stamp: $(net)
+	$(docker) build \
+		--build-arg DIR_BIN=$(dir_bin) \
+		--build-arg ENABLE_WARPED_EPOCH=$(warped) \
+		--file ./node/Dockerfile \
+		--tag $(docker_image) \
+		../
+	touch $(net)/image.stamp
+
+config: $(net)/docker-compose.yml
+$(net)/docker-compose.yml: genconfig.sh $(net) $(net)/image.stamp
+	./genconfig.sh
+
+_start: $(net)/run.stamp
+start: config image $(net)/run.stamp
+$(net)/run.stamp:
+	cd $(net); $(docker_compose) up --remove-orphans -d; $(docker) compose top
+	touch $(net)/run.stamp
+
+wait: $(net)/run.stamp
+	$(docker_run) $(docker_image) $(dir_bin)/fetch -f $(dir_base)/client/client.toml
+
+probe: $(net)/run.stamp
+	$(docker_run) $(docker_image) $(dir_bin)/walletshield \
+		-config $(dir_base)/client2/client.toml \
+		-log_level DEBUG \
+		-probe \
+		-probe_count $(probe_count)
+
+.PHONY: stop
+stop:
+	[ -e $(net) ] && cd $(net) && $(docker_compose) down --remove-orphans
+	rm -fv $(net)/run.stamp
+
+.PHONY: clean
+clean: stop
+	$(docker) rmi $(docker_image)
+	rm -rfv $(net)

docker/README.md

@@ -1,10 +1,67 @@
-# Docker Test Network
+# Dockerized Test Networks
 
-The Makefile and scripts here allow developers of 0KN mix network apps and server-side plugins to
-locally run an offline Katzenpost test network with a podman-compatible docker-compose
-configuration. It is meant for developing and testing client and server mix network components as
-part of the core developer work flow.
+This directory provides Makefiles and scripts to set up a local, offline test network for developing
+and testing 0KN mix network applications and server-side plugins. The setup leverages a
+Podman-compatible `docker-compose` configuration for simulating a Katzenpost network environment.
 
-This Makefile covers 0KN-specifics and proxies other targets to Katzenpost's `docker/Makefile`.
-Refer to [Katzenpost Docker test network](https://github.com/katzenpost/katzenpost/tree/main/docker)
-for more info.
+The goal is to support core development workflows by enabling local testing of both client and
+server mix network components in isolated, controlled conditions.
+
+There are two Makefiles available, each corresponding to a different PKI.
+
+- **`Makefile`:** (Default) Manages a local test network using Katzenpost’s voting PKI.
+- **`Makefile.appchain`:** Uses 0KN’s ZKAppChain PKI.
+
+## Voting PKI
+
+This setup, managed by the default `Makefile`, covers 0KN-specifics and proxies other targets to
+Katzenpost's `docker/Makefile`. For additional details, refer to the [Katzenpost Docker Test
+Network documentation](https://github.com/katzenpost/katzenpost/tree/main/docker). The voting PKI
+functionality offers less complex local testing of 0KN mix plugins and client apps that do not
+require the appchain.
+
+## Appchain PKI
+
+This Makefile builds and manages a network of dockerized nodes from
+[`node/Dockerfile`](./node/Dockerfile). It uses the [genconfig](../genconfig/) utility to create
+configurations for nodes from the network info in [network.yml](./network.yml) using the
+appchain-powered [pki](../pki/). Node interactions with the appchain are managed through the
+appchain-agent, utilizing UNIX domain sockets for communication.
+
+### Prerequisites
+
+To run the Appchain PKI network, ensure the following components are available:
+
+- [appchain-agent](https://github.com/0KnowledgeNetwork/appchain-agent) Docker image
+- An operational 0KN ZKAppChain
+
+### Example Workflow
+
+```bash
+# build the appchain-agent docker image
+cd appchain-agent && make image
+
+# start local appchain instance, then:
+
+# build the docker image, configure, start the network, wait for the epoch, then probe
+net=/tmp/appchain-mixnet make -f Makefile.appchain start wait probe
+
+# stop the network and clean up
+net=/tmp/appchain-mixnet make -f Makefile.appchain clean
+
+# build the docker image and configure (without starting network)
+# to inspect or manually edit the configuration files before continuing
+net=/tmp/appchain-mixnet make -f Makefile.appchain config
+
+# start the network without rebuilding or reconfiguring, wait for the epoch
+net=/tmp/appchain-mixnet make -f Makefile.appchain _start wait
+
+# test the network with a client sending 10 test probes
+net=/tmp/appchain-mixnet probe_count=10 make -f Makefile.appchain probe
+
+# watch log files
+tail -f /tmp/appchain-mixnet/*/*.log
+
+# stop the network (without cleaning up)
+net=/tmp/appchain-mixnet make -f Makefile.appchain stop
+```

docker/genconfig.sh

@@ -1,31 +1,33 @@
-#!/bin/bash
+#!/bin/bash -e
 
-# This script is invoked by ./Makefile to generate config files for a local
-# test network using appchain pki. Variables set by the Makefile are read from
-# the environment. This is intended to be run from within the katzenpost docker
-# container.
+# This script is invoked by ./Makefile to generate a docker-compose.yml file
+# for a local test network using appchain pki. Variables set by the Makefile
+# are read from the environment.
 
 port=30000
-dir_base="/${net_name}"
-dir_out=${dir_base}
-binary_suffix=".${distro}"
-
-rm -rf ${dir_out} && mkdir -p ${dir_out}
+dir_out=${net}
 
 echo "Generating config files for local network:"
-echo "  num gateways: ${gateways}"
-echo "  num servicenodes: ${serviceNodes}"
-echo "  num mixes: ${mixes}"
-echo "  binary-suffix: ${binary_suffix}"
-echo "  distro: ${distro}"
-echo "  dir-base: ${dir_base}"
-echo "  dir-out: ${dir_out}"
-
-gencfg="../genconfig/cmd/genconfig/genconfig \
-  -input ./network.yml \
-  -binary-suffix ${binary_suffix} \
-  -dir-base ${dir_base} \
-  -dir-out ${dir_out}"
+echo "  dir_base: ${dir_base}"
+echo "  dir_bin: ${dir_bin}"
+echo "  dir_out: ${dir_out}"
+echo "  docker_image: ${docker_image}"
+echo "  docker_image_agent: ${docker_image_agent}"
+echo "  num_gateways: ${num_gateways}"
+echo "  num_servicenodes: ${num_servicenodes}"
+echo "  num_mixes: ${num_mixes}"
+
+gencfg="${docker} run ${docker_args} --rm \
+  --volume $(readlink -f ./network.yml):/tmp/network.yml \
+  --volume $(readlink -f ${dir_out}):${dir_base} \
+  ${docker_image} \
+  ${dir_bin}/genconfig \
+    -input /tmp/network.yml \
+    -binary-prefix ${dir_bin}/ \
+    -dir-base ${dir_base} \
+    -dir-out ${dir_base}"
+
+echo "genconfig: ${gencfg}"
 
 cat <<EOF > ${dir_out}/prometheus.yml
 scrape_configs:
@@ -38,9 +40,10 @@ EOF
 cat <<EOF > ${dir_out}/docker-compose.yml
 x-common-service: &common-service
   restart: "no"
-  image: katzenpost-${distro}_base
+  image: ${docker_image}
+  user: ${docker_user}
   volumes:
-    - ./:${dir_base}
+    - ${dir_out}:${dir_base}
   network_mode: host
 
 services:
@@ -49,7 +52,7 @@ services:
     restart: "no"
     image: docker.io/prom/prometheus
     volumes:
-      - ./:${dir_base}
+      - ${dir_out}:${dir_base}
     command: --config.file="${dir_base}/prometheus.yml"
     network_mode: host
 
@@ -58,30 +61,53 @@ EOF
 function gencfg_node () {
   type=${1}
   id=${type}${2}
+  metrics="127.0.0.1:$((port+2))"
+
+  ${gencfg} \
+    -type ${type} \
+    -identifier ${id} \
+    -metrics ${metrics} \
+    -port ${port} \
+    || exit 1
 
-  ${gencfg} -port ${port} -type ${type} -identifier ${id} || exit 1
+  echo "    - ${metrics}" >> ${dir_out}/prometheus.yml
 
-  echo "    - 127.0.0.1:${port}" >> ${dir_out}/prometheus.yml
-  port=$((port+2))
+  # increment port for the next node
+  port=$((port+10))
 
   cat <<EOF >> ${dir_out}/docker-compose.yml
+  ${id}-agent:
+    <<: *common-service
+    image: ${docker_image_agent}
+    command: >
+      pnpm run agent \
+        --ipfs \
+        --ipfs-data ${dir_base}/ipfs-data \
+        --listen \
+        --key ${dir_base}/${id}-auth/appchain.key \
+        --socket ${dir_base}/${id}-auth/appchain.sock \
+        --socket-format cbor \
+        --tx-status-retries 20 \
+        --debug
+
   ${id}-auth:
     <<: *common-service
-    command: ${dir_base}/pki${binary_suffix} -f ${dir_base}/${id}-auth/authority.toml
+    command: ${dir_bin}/pki -f ${dir_base}/${id}-auth/authority.toml
+    depends_on:
+      - ${id}-agent
 
   ${id}:
     <<: *common-service
-    command: ${dir_base}/server${binary_suffix} -f ${dir_base}/${id}/katzenpost.toml
+    command: ${dir_bin}/server -f ${dir_base}/${id}/katzenpost.toml
     depends_on:
       - ${id}-auth
 
 EOF
 }
 
-for i in $(seq 1 ${gateways}); do gencfg_node gateway ${i}; done
-for i in $(seq 1 ${serviceNodes}); do gencfg_node servicenode ${i}; done
-for i in $(seq 1 ${mixes}); do gencfg_node mix ${i}; done
-
-# FIXME: client*/config.toml generated with, to include, gateway('s auth)
-# ${gc} -type client1
-# ${gc} -type client2
+for i in $(seq 1 ${num_mixes}); do gencfg_node mix ${i}; done
+for i in $(seq 1 ${num_gateways}); do gencfg_node gateway ${i}; done
+for i in $(seq 1 ${num_servicenodes}); do
+  gencfg_node servicenode ${i}
+  cp ../server_plugins/cbor_plugins/http_proxy/http_proxy_config.toml ${dir_out}/servicenode${i}/http_proxy_config.toml
+done

docker/network.yml

@@ -1,6 +1,6 @@
 # Example network configuration file; configures local test network using appchain pki
 build_datetime: '1728353595'
-kp_client_debug_DisableDecoyTraffic: false
+kp_client_debug_DisableDecoyTraffic: true
 kp_client_debug_EnableTimeSync: false
 kp_client_debug_InitialMaxPKIRetrievalDelay: 0
 kp_client_debug_PollingInterval: 0