Skip to main content

Deployment

zkCoins runs as Docker containers exposed via HTTPS. Documentation is deployed as a static site.

Architecture​

GitHub (push)
  │
  ├── develop → GitHub Actions → Docker build (ARM64)
  │                              → push zkcoin/*:beta
  │                              → SSH deploy to DEV server
  │
  └── main → GitHub Actions → Docker build (ARM64)
                              → push zkcoin/*:latest
                              → SSH deploy to PRD server

Static docs
  └── docs.zkcoins.app → Cloudflare Pages (auto-build on push)

URLs​

URLServiceEnvironment
zkcoins.comWhitepaper / Shielded CSV LandingPRD
dev.zkcoins.comWhitepaper Landing (preview)DEV
zkcoins.infoBrand-Hub / Landing (planned)PRD
zkcoins.appWallet AppPRD
api.zkcoins.appBackend APIPRD
docs.zkcoins.appDocumentationPRD
status.zkcoins.appStatus PagePRD
dev.zkcoins.appWallet AppDEV
dev-api.zkcoins.appBackend APIDEV
dev-docs.zkcoins.appDocumentationDEV
dev-status.zkcoins.appStatus PageDEV
zkcoins.exchangeTrading Venue (planned)PRD
dev.zkcoins.exchangeTrading Venue (planned)DEV
zkcoins.spaceExplorer (planned)PRD
dev.zkcoins.spaceExplorer (planned)DEV

Docker Images​

ImageDEV tagPRD tagRegistry
zkcoin/app:beta:latestDocker Hub
zkcoin/server:beta:latestDocker Hub

Docs are not containerized — deployed as static files via Cloudflare Pages.

Repositories​

RepoPurposeDeploy method
zk-coins/appWallet frontend (Next.js, PWA)Docker container
zk-coins/serverBackend API (Rust/Axum)Docker container
zk-coins/docsDocumentation (Docusaurus)Cloudflare Pages
zk-coins/researchProtocol research, upstream reposNot deployed

Git Workflow​

BranchPurposeDeploy targetProtection
developDefault branch, active developmentDEVRuleset (PR required)
mainProduction releasesPRDBranch protection (PR required)
Feature branchesIndividual changes—Merged to develop via PR

Workflow: feature branch → PR to develop → auto Release PR to main → merge to main

CI/CD Workflows​

Every repo has 3-4 workflows:

WorkflowTriggerAction
ci.yamlPush develop, PRLint + Build check
deploy-dev.yamlPush developDocker build (ARM64) → push :beta → deploy DEV
deploy-prd.yamlPush mainDocker build (ARM64) → push :latest → deploy PRD
auto-release-pr.yamlPush developCreates Release PR (develop → main)

GitHub Secrets​

Secrets are set at the org level (zk-coins) and available to all repos:

SecretPurpose
DEPLOY_DEV_SSH_KEYSSH private key for DEV server
DEPLOY_DEV_SSH_KNOWN_HOSTSHost key for DEV server
DEPLOY_DEV_HOSTDEV server SSH hostname
DEPLOY_DEV_USERDEV server SSH username
DEPLOY_PRD_SSH_KEYSSH private key for PRD server
DEPLOY_PRD_SSH_KNOWN_HOSTSHost key for PRD server
DEPLOY_PRD_HOSTPRD server SSH hostname
DEPLOY_PRD_USERPRD server SSH username
DOCKER_USERNAMEDocker Hub username (zkcoin)
DOCKER_PASSWORDDocker Hub access token

Running with Docker​

Wallet App​

docker run -p 3090:3090 \
  -e NEXT_PUBLIC_API_URL=https://api.zkcoins.app \
  -e NEXT_PUBLIC_NETWORK=mainnet \
  zkcoin/app:latest

Runtime env var injection via entrypoint.sh — same image for DEV and PRD.

Backend Server​

docker run -p 4242:4242 \
  --network bitcoin \
  -e ESPLORA_URL=http://bitcoind:8332 \
  -e BITCOIN_RPC_USER=myuser \
  -e BITCOIN_RPC_PASSWORD=mypassword \
  zkcoin/server:latest

Requires a Bitcoin node. See Backend documentation.

Health Checks​

ContainerHealth checkHealthy response
zkcoins-appcurl -f http://localhost:3090/HTTP 200
zkcoins-serverwget http://localhost:4242/healthHTTP 200 (ok)

Monitoring​

Port Allocation​

PortService
6090Wallet App (host-side)
6091Explorer (planned)
6093Backend API (host-side)
3090App internal (inside container)
4242Server internal (inside container)