blockchain/docker

Lethean Testnet — Docker Deployment

Run the full Lethean ecosystem in Docker. No compilation needed.

Deployment Options

Compose File	For	Services
docker-compose.node.yml	Home node operator	Daemon + wallet (PoS staking)
docker-compose.exit.yml	VPN exit node operator	Daemon + wallet + WireGuard
docker-compose.pull.yml	Full ecosystem	All 8 services + databases

Helper Scripts

bash demos/helpers/chain-info.sh      # Chain height, difficulty, status
bash demos/helpers/chain-aliases.sh   # List on-chain aliases
bash demos/helpers/wallet-address.sh  # Show your wallet address
bash demos/helpers/wallet-balance.sh  # Check LTHN balance
bash health.sh                        # Full ecosystem health check

Quick Start

# 1. Configure
cp .env.example .env
# Edit .env — at minimum change JWT_SECRET and WALLET_PASSWORD

# 2. Start
docker compose -f docker-compose.pull.yml up -d

# 3. Check
docker compose -f docker-compose.pull.yml ps

The daemon takes ~30 seconds to initialise the chain database on first run. Other services wait for the daemon health check before starting.

Services

Service	URL	Description
Block Explorer	http://localhost:3335	Browse blocks, transactions, aliases
Trade DEX	http://localhost:3338	Decentralised exchange frontend
Trade API	http://localhost:3336	REST API for trade operations
Mining Pool	http://localhost:2117	Pool stats API
Pool Stratum	localhost:5555	Connect miners here
LNS	http://localhost:5553	Lethean Name Service HTTP API
LNS DNS	localhost:5354	DNS resolver for .lthn names
Daemon RPC	http://localhost:46941	Chain node JSON-RPC
Wallet RPC	http://localhost:46944	Wallet JSON-RPC
Docs	http://localhost:8099	Documentation site

Mining

Connect a ProgPoWZ miner to the pool stratum:

stratum+tcp://YOUR_IP:5555

Compatible miners:

• progminer (recommended) — progminer -P stratum+tcp://YOUR_WALLET_ADDRESS@localhost:5555
• T-Rex — ProgPoWZ algorithm
• TeamRedMiner — ProgPoWZ algorithm

Wallet

The wallet auto-creates on first start. To check your balance:

curl -s http://localhost:46944/json_rpc \
  -d '{"jsonrpc":"2.0","id":"0","method":"getbalance"}' \
  -H 'Content-Type: application/json'

The wallet runs with PoS mining enabled (--do-pos-mining), so it will stake any balance automatically.

Chain Status

curl -s http://localhost:46941/json_rpc \
  -d '{"jsonrpc":"2.0","id":"0","method":"getinfo"}' \
  -H 'Content-Type: application/json' | python3 -m json.tool

Volumes

Volume	Contains	Backup?
chain-data	Blockchain database (LMDB)	Optional — can resync
wallet-data	Wallet file + keys	Critical — back up regularly
explorer-db	Explorer PostgreSQL	Can recreate from chain
trade-db	Trade PostgreSQL	Important for trade history

Backup wallet

docker compose -f docker-compose.pull.yml stop wallet
docker cp lthn-wallet:/wallet ./wallet-backup-$(date +%Y%m%d)
docker compose -f docker-compose.pull.yml start wallet

Ports

All ports can be changed via .env. See .env.example for the full list.

If you're running behind a firewall and want external access:

• P2P: Open port 46942 (TCP) for other nodes to connect
• Stratum: Open port 5555 (TCP) for external miners
• Explorer: Open port 3335 (TCP) for public block explorer

Troubleshooting

Daemon crashes on start: Check logs with docker logs lthn-daemon. Common causes:

• Port already in use — change ports in .env
• Corrupt chain data — remove volume: docker volume rm docker_chain-data

Wallet shows 0 balance: The wallet needs to sync with the daemon first. Check sync status in daemon logs. New wallets start empty — mine or receive LTHN to fund them.

Pool shows "Daemon died": The pool needs both the daemon and wallet running. Check both are healthy:

docker compose -f docker-compose.pull.yml ps daemon wallet

Explorer shows "offline": The explorer connects to the daemon internally. If the daemon is still syncing, the explorer will show offline until sync completes.

Stopping

docker compose -f docker-compose.pull.yml down        # stop containers
docker compose -f docker-compose.pull.yml down -v      # stop + delete data

Building from Source

If you want to build the images yourself instead of pulling pre-built ones:

docker compose -f docker-compose.ecosystem.yml build
docker compose -f docker-compose.ecosystem.yml up -d

This requires the full source tree — see the main repository README.