Edit

Awakening Testnet Node Setup Guide

Automation helpers for running and maintaining a BlockDAG testnet node with Docker. The scripts wrap the provided docker-compose.yml so you can bring a node up with a single command, manage restarts, and safely wipe local state when needed.

Table of Contents

  • Features

  • Repository Layout

  • Requirements

  • Setup

  • Running the Node

  • Maintenance Tasks

  • Troubleshooting

  • Data & Security Notes

  • Reference: Docker Compose Service

  • Support

Features

  • Single-entrypoint script (blockdag.sh) that loads your mining address and launches Docker Compose.

  • Cross-platform Docker Compose detection (node.sh) compatible with Compose v1 and v2 syntaxes.

  • Opinionated directory structure for persisted blockchain data, logs, and binaries under bin/bdag/.

  • Sample environment file (.env) for storing wallet configuration.

  • Optional Linux helper to install Docker & Docker Compose (install_docker.sh).

Repository Layout

blockdag.sh             # Primary launcher – loads wallet and calls node.sh
node.sh                 # Starts docker compose with the provided mining address
restart.sh              # Stops current stack, removes image, restarts with existing data
restartWithCleanup.sh   # Same as above, but wipes ./bin/bdag before restart
install_docker.sh       # Ubuntu-based helper to install Docker & docker-compose
docker-compose.yml      # Defines the BlockDAG worker service and persisted volumes
bin/bdag/data           # Blockchain data volume (created at runtime)
bin/bdag/logs           # Node log output (created at runtime)
.env                    # Optional environment file (example provided)
wallet.txt              # Optional file containing wallet info, last line read as mining address

Note: bin/bdag/data and bin/bdag/logs may be empty until the node runs. If they contain testnet data generated by previous runs, they might require elevated permissions to inspect or delete.

Requirements

Operating Systems

  • Linux (Ubuntu/Debian, Fedora, Arch, etc.): fully supported. Scripts assume a POSIX shell and Docker.

  • macOS (Ventura 13+ recommended): supported as long as Docker Desktop is installed.

  • Windows: run inside WSL2 or another Linux-like environment. Native PowerShell is not supported by these scripts.

Software

  • Docker Engine & Docker Compose v1 or v2.

  • Git (to clone the repository).

  • bash (all scripts use Bash features).

Optional for Linux users:

  • curl, apt, etc. – install_docker.sh targets Ubuntu 20.04+ and requires root.

Hardware Guidelines

  • CPU: Minimum 4 cores (4+ cores recommended for mining).

  • Memory (RAM): At least 8GB (8GB+ recommended).

  • Disk Space: Minimum 20GB of free disk space. More storage is recommended depending on the size of the blockchain and logs.

  • Network: A stable internet connection with sufficient bandwidth.

Wallet Format Notice

  • BlockDAG nodes now use EVM-compatible public addresses (0x…) for mining rewards.

  • Legacy UTXO-based PK addresses are no longer supported. Update any automation, scripts, or stored credentials to point to an EVM wallet before starting the node.

Setup

  1. Clone the repository

    git clone https://github.com/BlockdagNetworkLabs/blockdag-scripts.git
cd blockdag-scripts

  2. Configure your mining address

    • Option A: edit .env and set PUB_ETH_ADDR=<your_evm_wallet_address>.

    • Option B: create wallet.txt where the last line contains your wallet address (e.g. exported from another tool).

    If both exist, .env takes precedence.

    Network note: These scripts target the latest EVM-based BlockDAG network only. Do not reuse legacy UTXO addresses; configure a 0x-prefixed EVM wallet for mining rewards.

  3. Verify Docker access

    docker --version
docker compose version  # or docker-compose --version

    If Docker is not installed on Ubuntu, you can adapt the provided install_docker.sh script (requires sudo).

  4. Allow Docker to create local directories Ensure your user has permissions to write to bin/bdag/. The directory is created automatically, but on Linux you may need to chown it if Docker runs as root.

Address Format Update (EVM Only)

  • BlockDAG mining rewards are now paid to Ethereum-style accounts. Supply an 0x-prefixed EVM public address wherever the scripts expect PUB_ETH_ADDR.

  • If you are migrating from earlier releases that referenced UTXO/PK addresses, regenerate or import an EVM wallet and update .env or wallet.txt accordingly.

  • Remove any legacy environment variables or files that still contain the deprecated address format to avoid accidental misconfiguration.

Running the Node

  1. Launch the node (prompts will depend on your shell configuration):

    ./blockdag.sh

    The script resolves your address, exports it as PUB_ETH_ADDR, and calls node.sh.

  2. node.sh selects the correct Docker Compose syntax for your installation and starts the stack with MINING_ADDRESS set from your EVM wallet.

  3. Once the containers are up:

    docker ps            # Verify the blockdag-testnet-network container is running
tail -f bin/bdag/logs/node.log  # Replace with actual filename after first run

To stop the node without cleaning data:

docker compose down    # or docker-compose down

Maintenance Tasks

Use the helper scripts at the repository root:

  • restart.sh – shuts down Docker Compose, removes the blockdagnetwork/awakening image if present, and relaunches using your configured wallet.

  • restartWithCleanup.sh – same as above but also clears ./bin/bdag/* (data, logs, any cached binaries). Back up your wallet before running this.

  • install_docker.sh – Ubuntu/WSL convenience installer. Review the script before executing (sudo ./install_docker.sh).

Manual alternatives:

# Pull the latest image
MINING_ADDRESS=$PUB_ETH_ADDR docker compose pull

# View logs
docker compose logs -f

# Remove volumes and containers
docker compose down --volumes

Troubleshooting

  • "PUB_ETH_ADDR not set": Confirm .env or wallet.txt exists and the address is on the last line. Reload your shell if you edited .env while a session was running.

  • Docker permission denied: Add your user to the docker group (sudo usermod -aG docker $USER) and restart your session, or run the scripts with sudo.

  • Node restarts on launch: Inspect bin/bdag/logs for recent log files. If corruption errors appear, run ./restartWithCleanup.sh to wipe local state.

  • Port conflicts: Default ports 38131, 18545, 18546, and 18150 must be free. Stop other services using them or edit docker-compose.yml.

  • Windows path issues: Ensure the repository lives inside your WSL filesystem (e.g. /home/<user>), not the mounted C: drive, to avoid Docker volume permission problems.

Data & Security Notes

  • The wallet address (PUB_ETH_ADDR) is injected into the container as MINING_ADDRESS. It must be an EVM address; do not reuse retired UTXO-style identifiers.

  • Do not commit .env or wallet.txt with real keys.

  • Blockchain data persists in bin/bdag/data/. Back it up before destructive operations.

  • Logs populate bin/bdag/logs/ and may contain sensitive operational details; sanitize before sharing.

  • Consider rotating Docker logs or mounting external storage if running long-term.

Reference: Docker Compose Service

docker-compose.yml launches a single service named nodeworker based on abhishek1857/blockdag:worker-20250923-102625. Key settings:

  • Ports: 38131 (RPC), 18545 (HTTP), 18546 (WebSocket), 18150 (peer).

  • Volumes:

    • bdag_bin named volume mounted at /opt/bdag inside the container.

    • Local ./bin/bdag/data → /bdag/data for chain data.

    • Local ./bin/bdag/logs → /bdag/logs for logs.

  • Environment: NODE_ARGS assembles testnet flags, mining options, CORS/websocket settings, and seeds a peer.

Customize the image tag or arguments directly in docker-compose.yml if the network releases new versions.

PreviousNodes and MiningNextBlockDAG Architecture

Last updated

Was this helpful?