Digitalia Archive Node — Administrator Guide¶

Purpose¶

This guide is for infrastructure operators and SRE teams managing Digitalia Archive Node environments in staging and production.

Use this guide together with:

JFOS_ARCHIVE_NODE_PRODUCTION_OPS_RUNBOOK.md
docs/FULL_NODE_ADMINISTRATOR_GUIDE.md
docs/IT_OPERATIONS_MANUAL.md

1. Archive Node Overview¶

An Archive Node stores full historical chain state and supports deep historical RPC queries that a pruned full node cannot reliably answer.

Typical roles:

historical RPC backend for analytics/indexers
compliance and forensic query source
long-range state queries for tooling and research

Primary interfaces:

Port	Protocol	Purpose
8545	TCP	JSON-RPC HTTP
8546	TCP	JSON-RPC WebSocket
30303	TCP/UDP	P2P
9090	TCP	Metrics

2. Capacity and Prerequisites¶

Resource	Recommended baseline
CPU	12+ vCPU
Memory	32+ GB RAM
Storage	2 TB+ fast SSD/NVMe, expandable
Network	Stable high-bandwidth connectivity, low packet loss

Archive mode requires:

pruning disabled
persistent data volumes
backup/snapshot strategy for large state growth

3. Deployment¶

3.1 Docker deployment¶

docker run -d \
  --name digitalia-archive \
  --restart unless-stopped \
  --security-opt no-new-privileges:true \
  --cap-drop ALL \
  -p 8545:8545 -p 8546:8546 -p 30303:30303 -p 9090:9090 \
  -v digitalia-archive-data:/opt/digitalia/data \
  -v digitalia-archive-state:/opt/digitalia/archive \
  -e DIGITALIA_NETWORK=mainnet \
  -e JAVA_OPTS="-Xms8g -Xmx16g -XX:+UseG1GC" \
  cosimousa/digitalia-archive-node:latest

3.2 Cold start behavior¶

Initial archive sync can take many hours depending on network height and I/O throughput. Track sync status continuously and do not expose the node as production-ready until syncing is complete.

3.3 Warm restart¶

docker stop --time=60 digitalia-archive
docker start digitalia-archive

4. Operational Validation¶

4.1 Liveness and readiness¶

curl -sf http://localhost:8545/health/live
curl -sf http://localhost:8545/health/ready

4.2 Core RPC checks¶

curl -s -X POST http://localhost:8545 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":1}'

curl -s -X POST http://localhost:8545 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"dvm_syncing","params":[],"id":1}'

curl -s -X POST http://localhost:8545 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"dvm_blockNumber","params":[],"id":1}'

4.3 Archive-state verification¶

Perform historical state query checks at older blocks to verify archive behavior.

curl -s -X POST http://localhost:8545 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"dvm_getBalance","params":["0x0000000000000000000000000000000000000001","0x1"],"id":1}'

5. Monitoring and Alerting¶

Minimum alert set:

peer count at zero
sync stalled for prolonged interval
disk usage above 80%
repeated container restarts
RPC error rate spike

Suggested operational metrics:

current block height
sync lag
peer count
process memory
storage growth rate

6. Incident Response¶

6.1 Archive node not syncing¶

verify peers are connected
verify data volume is writable and not full
inspect logs for storage/database errors
restart and re-check sync progress trend

6.2 Historical queries failing¶

confirm node is archive mode
verify pruning settings remain disabled
validate query block height exists in chain history
if corruption suspected, run storage checks and restore snapshot

6.3 Disk exhaustion¶

stop heavy query traffic temporarily
expand volume
clean non-critical logs/artifacts
resume with monitoring of growth trend

6.4 Crash loop¶

inspect OOM and JVM settings
adjust memory limits and JAVA_OPTS coherently
verify permissions of mounted volumes
rollback image if regression introduced

7. Security and Hardening¶

run with least privilege, no-new-privileges, and dropped capabilities
restrict RPC exposure to trusted networks or API gateways
monitor vulnerability scans for archive-node images
enforce change control on runtime flags affecting pruning/sync mode

8. Rollback and Recovery¶

Image rollback:

docker stop digitalia-archive && docker rm digitalia-archive
# re-run with previous known-good tag

Recovery baseline:

restore from latest valid snapshot if needed
verify liveness and sync status
run historical state query smoke checks

9. Documentation Map¶

docs/ARCHIVE_NODE_ADMINISTRATOR_GUIDE.md (this file)
docs/ARCHIVE_NODE_USER_MANUAL.md
JFOS_ARCHIVE_NODE_PRODUCTION_OPS_RUNBOOK.md
docs/FULL_NODE_ADMINISTRATOR_GUIDE.md
docs/IT_OPERATIONS_MANUAL.md