> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quantumapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Running a node

> Day-2 operations for a Quantum Chain node — startup, monitoring, upgrades.

This page covers the operational lifecycle of a Quantum Chain node after it's installed.

## Startup

A typical systemd unit:

```ini theme={null}
# /etc/systemd/system/geth.service
[Unit]
Description=Quantum Chain geth
After=network-online.target

[Service]
Type=simple
User=geth
ExecStart=/usr/local/bin/geth \
  --datadir /var/lib/geth \
  --networkid 20803 \
  --syncmode snap \
  --http --http.addr 127.0.0.1 --http.api eth,net,web3 \
  --metrics --metrics.addr 127.0.0.1 --metrics.port 6060
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
```

```bash theme={null}
systemctl enable --now geth
journalctl -u geth -f
```

## Health and readiness

Quantum Chain exposes the standard geth health endpoints:

| RPC method        | Purpose                                             |
| ----------------- | --------------------------------------------------- |
| `eth_blockNumber` | Latest block; should advance every \~15s on mainnet |
| `eth_syncing`     | Returns sync status; `false` when fully synced      |
| `net_peerCount`   | Number of connected peers                           |
| `admin_nodeInfo`  | Node identity, enode URL                            |

A simple liveness probe:

```bash theme={null}
curl -s -X POST http://127.0.0.1:8545 \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","id":1,"params":[]}' \
  | jq -r '.result'
```

## Metrics

Enable Prometheus-compatible metrics with:

```bash theme={null}
geth ... --metrics --metrics.addr 0.0.0.0 --metrics.port 6060
```

Key metrics:

| Metric                       | Meaning                                            |
| ---------------------------- | -------------------------------------------------- |
| `chain/head/block`           | Latest block number                                |
| `chain/head/header`          | Latest header number; `block - header` should be 0 |
| `eth/db/chaindata/disk/size` | Database size in bytes                             |
| `p2p/peers`                  | Peer count                                         |
| `txpool/pending`             | Pending transactions in pool                       |
| `txpool/queued`              | Future transactions                                |
| `system/cpu/sysload`         | OS CPU load                                        |

## Logs

Logs are structured. Increase verbosity with:

```bash theme={null}
geth --verbosity 4    # 0=silent ... 5=debug
```

Or per-module via `--vmodule consensus=4,p2p=3`.

## Sync states

| State                     | Meaning                               |
| ------------------------- | ------------------------------------- |
| Receiving headers         | First phase of snap sync              |
| Importing block headers   | Header chain catching up              |
| Importing snapshot chunks | Downloading the latest state snapshot |
| Block synchronization     | Block bodies and receipts             |
| Synced                    | Up to head; tracking new blocks       |

## Backups

Snap and full sync nodes are stateless — you can wipe and resync. Archive nodes hold irreplaceable historical state; back them up with:

```bash theme={null}
systemctl stop geth
tar -C /var/lib --use-compress-program=zstd -cf /backup/geth-$(date +%F).tar.zst geth
systemctl start geth
```

For online backups without stopping the node, use a copy-on-write filesystem (ZFS, btrfs).

## Upgrades

Quantum Chain releases ship as tagged commits in this repository.

1. Read the release notes for hard-fork activation blocks.
2. Build the new binary on a staging node.
3. Update validators within the upgrade window — sealers running an outdated binary after the fork height will produce blocks rejected by the network.
4. Roll RPC nodes after validators.

## Pruning

To reclaim disk on a `--gcmode full` node:

```bash theme={null}
systemctl stop geth
geth snapshot prune-state --datadir /var/lib/geth
systemctl start geth
```

`prune-state` rewrites the trie and may take several hours.

## Where to go next

* [Configuration](/quantum-chain/configuration)
* [Operating a network](/quantum-chain/networks)
* [Troubleshooting](/quantum-chain/troubleshooting)