Network separation
Keep Mainnet and Apothem data, keys and configuration distinct. Before signing a staking action, compare the wallet network with the node network.
NODE OPERATIONS
Deploy XDC with Docker
Prepare a server, configure a node, verify synchronization and keep your deployment maintainable.
On this page
Docker packages the node software and its runtime dependencies. You still operate the host, storage, keys, connectivity and upgrade process.
Choose Mainnet or Apothem first. A synchronized data node and a registered masternode candidate are different milestones; installation does not stake funds or guarantee validator selection.
Published hardware guidance varies between the setup page, architecture guide and snapshot instructions. Treat the figures below as the Docker page’s planning baseline and confirm current release requirements before provisioning.
A practical starting configuration
| Item | Details |
|---|---|
The Docker page names CentOS, Red Hat Enterprise Linux and Ubuntu 20.04+. The current repository instructions focus on Ubuntu 20.04 or later. Choose a supported OS release and verify the installer’s compatibility. | |
Published Docker-page baseline: a 64-bit x86_64 processor with at least 6 cores. Match capacity to the selected client and workload. | |
Published Docker-page baseline: at least 32 GB RAM. Other XDC guides quote different figures for different setups; inspect the requirements for your actual mode. | |
Published Docker-page baseline: an 800 GB SSD database partition and at least 500 IOPS. Allow additional capacity for chain growth, restoration and backups; archive workloads need their own sizing. | |
The current repository calls for Docker Engine 24.0+, Compose v2.20+, curl and jq. Older documentation still shows the docker-compose command; follow the current repository for supported tooling. | |
Operator documentation calls for a publicly reachable server. Plan peer connectivity, administrative access and any application API exposure as separate network requirements. |
Deploy in a controlled sequence
1. Choose the network and role
Use Apothem to rehearse deployment and recovery. Decide whether the node serves data, retains archive state or participates as a validator/standby candidate.
Explore resource2. Prepare the host
Update the operating system, establish SSH key access and preserve a provider-console recovery path. Confirm storage mounts and available disk before installing the node.
Explore resource3. Review the official repository
Read the current XinFinOrg/XinFin-Node instructions and release changes. Retrieve the supported deployment files rather than copying an unmaintained tutorial.
Explore resource4. Install the container tooling
Install the Docker and Compose versions expected by the current release. Check that the container engine starts correctly before configuring the blockchain service.
Explore resource5. Create the network configuration
Work in the selected mainnet or testnet directory. Create .env from env.example only for a new setup; preserve an existing configuration. Set the instance identity and contact fields as documented.
Explore resource6. Review exposed services
A validator-only node does not need a public application API. Review ENABLE_RPC, ENABLE_WS, permitted API namespaces, firewall rules and container port mappings before starting.
Explore resource7. Start and observe
The repository uses docker compose -f docker-compose.yml up -d from the selected network directory. Check the container, logs, peer connectivity and advancing block height; a running container alone does not prove synchronization.
Explore resource8. Complete the appropriate next step
For data access, validate the queries your application needs. For candidacy, retrieve the node address and follow the staking workflow only after the node is healthy.
Explore resource
Keep configuration and key ownership clear
Instance identity
Preserve the existing INSTANCE_NAME during upgrades. Review configuration changes deliberately so monitoring and operational records continue to identify the correct node.
Node address
The repository identifies xdcchain/coinbase.txt as the address reference. Back up the associated signing material; that public text file alone is not sufficient for recovery.
RPC and WebSocket access
The repository defaults both interfaces to disabled. Enabling them is an explicit service decision; restrict access and expose only the methods your application needs.
Version-sensitive settings
Current repository documentation combines API configuration and changes some older address/origin variables. Compare your existing .env with the release’s sample before restarting.
Know when the node is ready
Check the process
Confirm the expected container is running and inspect logs for repeated errors or restarts. Record the software version before troubleshooting.
Explore resourceCheck progress and peers
A healthy process must also find peers and advance its local chain. Compare its progress with a trusted network reference; do not treat an empty or stale dashboard as evidence of completion.
Explore resourceCheck the intended service
For an RPC service, validate representative reads against the correct chain. For a validator, confirm candidacy and participation separately from ordinary synchronization.
Explore resourceCheck the recovery plan
Make sure the operator can recover configuration and keys without relying on a single server. A chain-data snapshot and a key backup solve different problems.
Explore resource
Operate beyond the first start
Snapshot restoration
Choose a snapshot matching the network, client and full/archive mode. Stop the node before replacing chain data, retain a recoverable backup and follow the source’s current extraction instructions.
Planned upgrades
Read release notes, preserve .env and keystores, and schedule the restart. After upgrading, check synchronization, connectivity and the role-specific service before declaring the node healthy.
Capacity monitoring
Watch disk headroom, memory, CPU, I/O and chain progress. An installation minimum is not a promise that the same server will suit future state growth or application load.
Participation monitoring
Validators should monitor signing and availability, not just container uptime. The slashing documentation describes how missed participation affects eligibility and recovery.
Resolve problems with useful evidence
1. Collect the relevant facts
Record the network, client version, operating system, Docker/Compose versions, local block progress, peer situation and the exact error. Note when the problem began and what changed.
Explore resource2. Narrow the failure
Distinguish a host-access issue, a container failure, a synchronization problem and an application API failure. Check the corresponding logs and configuration before making another change.
Explore resource3. Ask with a reproducible report
Post the relevant environment details, error and actions already tried in the developer forum or repository issue tracker. Redact credentials, keys, recovery phrases and unrelated personal information.
Explore resource4. Verify the fix
After recovery, confirm the node advances, answers the intended requests and resumes any required participation. Record the change so another operator can reproduce it.
Explore resource
Watch the original setup walkthroughs
These are the two videos embedded on the original Docker page. They demonstrate earlier setup workflows; use the current repository for command versions and security defaults.
Video
Mainnet bootstrap on AWS
The original bootstrap walkthrough linked from the Docker setup page.
Check commands against current release
Video
Mainnet Docker deployment on AWS
The original Docker walkthrough linked from the Docker setup page.
Check commands against current release
Continue with official operating resources
Node operator documentation
Read the installation, staking, snapshot and operating instructions maintained in the XDC documentation.
XDC developer forum
Describe a reproducible problem, explain your environment and share redacted logs with other operators.
Developer community on Telegram
Join the community channel linked from the official setup pages. Never share keystores, private keys or wallet recovery phrases.
AI technical support
Explore the developer-assistance destination linked by the network portal. Check suggested changes against the current repository before applying them.
SOURCE & CONTEXT
Content carried forward from XinFin’s public website and linked primary sources. Historical material is identified where applicable.
Source record Editorial methodology