# Node Setup Guide

Automation helpers for running and maintaining a BlockDAG mainnet 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](https://learn.microsoft.com/windows/wsl/install) 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.<br>

### Setup

1. **Clone the repository**

   ```bash
   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**

   ```bash
   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.<br>

### 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.<br>

### Running the Node

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

   ```bash
   ./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:

   ```bash
   docker ps            # Verify the blockdag-mainnet-network container is running
   docker logs -f <CONTAINER_NAME>  # Replace with actual container
   ```

To stop the node without cleaning data:

```bash
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:

```bash
# 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.<br>

### 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.<br>

### 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 mainnet 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blockdagnetwork.io/get-started/nodes-and-mining/node-setup-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.