Running Xone Chain Node in Docker

This guide provides a step-by-step process to run the Xone Chain node in a Docker container. This method is ideal for users who prefer containerized applications for easier management, deployment, and scaling.

1. Prerequisites

Operating System: Ubuntu 22.04 or 24.04
Node Initialization Completed
- You’ve already run xoned init locally or on the host and replaced genesis.json / config.toml / app.toml.
- The default data directory is /home/ubuntu/.xone (modify as needed).
Host Permissions
- The ubuntu user (or your chosen user) must have read/write access to /home/ubuntu/.xone.
- You need sudo privileges to install software and manage Docker.

2. Install Docker

# Update package list
sudo apt update
 
# Add Docker’s official GPG key
arch=$(dpkg --print-architecture)
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
 
# Add Docker stable repository
sudo add-apt-repository \
  "deb [arch=${arch}] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable"
 
# Install Docker Engine
sudo apt update
sudo apt install -y docker-ce
 
# Enable and start Docker service
sudo systemctl enable docker
sudo systemctl start docker
sudo systemctl status docker

Tip: To allow a non‑root user (e.g. ubuntu) to run Docker commands without sudo, add them to the docker group:
sudo usermod -aG docker ubuntu

3. Create the Launch Script

In any directory, create a file named docker_run.sh and paste the following:

#!/bin/sh
 
# —— Modify these variables as needed ——  
IMAGE_URL='xonechain/xoned:v1.0.1'    # Node image and version  
CONTAINER_NAME='xone-node'           # Container name  
DATA_DIR='/home/ubuntu/.xone'        # Host data directory  
RPC_PORT_HTTP=8545                   # JSON‑RPC HTTP port  
RPC_PORT_WS=8546                     # JSON‑RPC WebSocket port  
P2P_PORT=26656                       # P2P port  
P2P_RPC_PORT=26657                   # P2P RPC interface port  
PEER_PORT=26658                      # Alternate P2P port  
PROMETHEUS_PORT=26660                # Prometheus metrics port  
REST_PORT=1317                       # REST API port  
METRICS_PORT=9090                    # Prometheus exporter port  
GRPC_METRICS_PORT=9091               # gRPC exporter port  
 
# Remove any existing container
docker rm -f $CONTAINER_NAME 2>/dev/null
 
# Run the container
docker run -d \
  --name $CONTAINER_NAME \
  --restart always \
  -v $DATA_DIR:/root/.xone \
  -p $RPC_PORT_HTTP:8545 \
  -p $RPC_PORT_WS:8546 \
  -p $P2P_PORT:26656 \
  -p $P2P_RPC_PORT:26657 \
  -p $PEER_PORT:26658 \
  -p $PROMETHEUS_PORT:26660 \
  -p $REST_PORT:1317 \
  -p $METRICS_PORT:9090 \
  -p $GRPC_METRICS_PORT:9091 \
  $IMAGE_URL \
  xoned start \
    --pruning=nothing \
    --json-rpc.api eth,txpool,personal,net,debug,web3,miner \
    --api.enable \
    --json-rpc.enable \
    --json-rpc.address 0.0.0.0:8545 \
    --json-rpc.ws-address 0.0.0.0:8546

Notes:

-v $DATA_DIR:/root/.xone: Mounts your host’s data directory into the container for persistence.

--restart always: Ensures the container restarts on failure or host reboot.

--pruning=nothing: Retains full block history (change to syncable, default, etc., as desired).

--json-rpc.api: Specifies which RPC modules to enable.

Adjust port mappings to fit your firewall rules and network topology.

4. Set Permissions & Launch

# Make the script executable
chmod +x docker_run.sh
 
# Run the script with sudo
sudo ./docker_run.sh

To change the data directory or ports, update the variables at the top of the script—no other edits are required.

5. Check Container Status & Logs

# List running containers
docker ps
 
# Follow real‑time logs
sudo docker logs -f xone-node

6. Common Operations

Upgrade the Image

# Pull the latest tag
docker pull xonechain/xoned:latest
 
# Rerun the launch script
sudo ./docker_run.sh

Enter the Container for Debugging
```
docker exec -it xone-node /bin/sh
```

Purge Old Data

# Stop and remove the container
docker rm -f xone-node
 
# Remove the data directory
rm -rf /home/ubuntu/.xone
 
# Re‑initialize / copy configs, then rerun the script
./docker_run.sh

After completing these steps, your Xone Chain node will run in a Docker container with automatic restarts, persistent storage, and flexible port mappings—enabling efficient operations and rapid iteration.

Background Operation Using Snapshots