Using Docker

This guide describes how to deploy a Pharos node using Docker and Docker Compose.

📌 For the latest Docker image tag, see Current Node Versions.

Prerequisites

Component	Specification
CPU	32 cores, 2.8GHz or faster, AMD Milan EPYC or Intel Xeon Platinum
Memory	256 GB
Storage	5 TB SSD with at least 350MiB/s bandwidth and 30000 IOPS
Network Bandwidth	0.5 Gbps
Open Files Limit	ulimit -n ≥ 10000000

Additionally, ensure Docker is installed:

• Docker Engine 20.10+
• Docker Compose 2.0+

1. Create working directory

export WORKSPACE=pharos
mkdir -p /data/$WORKSPACE && cd /data/$WORKSPACE

2. Download configuration files

Download the genesis configuration and VERSION file based on your network:

For Atlantic Testnet:

mkdir -p bin
wget -O genesis.conf https://raw.githubusercontent.com/PharosNetwork/resources/refs/heads/main/atlantic.genesis
wget -O bin/VERSION https://raw.githubusercontent.com/PharosNetwork/resources/refs/heads/main/atlantic.version

For Mainnet:

mkdir -p bin
wget -O genesis.conf https://raw.githubusercontent.com/PharosNetwork/resources/refs/heads/main/mainnet.genesis
wget -O bin/VERSION https://raw.githubusercontent.com/PharosNetwork/resources/refs/heads/main/mainnet.version

Note: When upgrading to a new version, you must also re-download the VERSION file to keep it in sync.

Download the node configuration file (choose one based on your node type):

For Archive/Full/Validator Node:

wget -O pharos.conf https://raw.githubusercontent.com/PharosNetwork/resources/refs/heads/main/conf/full.conf

Note: Pruning is disabled by default. To enable pruning, see Enable Pruning in Pharos Node.

For TraceDB Node:

wget -O pharos.conf https://raw.githubusercontent.com/PharosNetwork/resources/refs/heads/main/conf/traceDB.conf

3. Create docker-compose.yml

Create the Docker Compose configuration file:

cat > docker-compose.yml <<EOF
services:
  pharos:
    image: public.ecr.aws/k2g7b7g1/pharos:pharos_community_v0.15.0_d6d98fd3_0720
    container_name: pharos-node
    environment:
      - CONSENSUS_KEY_PWD=YOUR_PASSWORD_HERE  # Change this to your password
      - PHAROS_CONF=/data/pharos.conf
      - GENESIS_CONF=/data/genesis.conf
      - KEYS_DIR=/data/keys
    volumes:
      # Mount data directory
      - /data/$WORKSPACE:/data
    ports:
      - "18100:18100"  # HTTP RPC
      - "18200:18200"  # WebSocket
      - "19000:19000"  # P2P TCP
      - "20000:20000"  # RPC
    restart: unless-stopped
    ulimits:
      nofile:
        soft: 10000000
        hard: 10000000
    healthcheck:
      test: ["CMD", "curl", "-sf", "-X", "POST", "-H", "Content-Type: application/json", "-d", "{\"jsonrpc\":\"2.0\",\"method\":\"eth_blockNumber\",\"params\":[],\"id\":1}", "http://localhost:18100"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
EOF

Note: The image uses a specific version tag (pharos_community_v0.15.0_d6d98fd3_0720).

4. Set password in docker-compose.yml

Edit docker-compose.yml and set your password:

vim docker-compose.yml

Change this line:

- CONSENSUS_KEY_PWD=YOUR_PASSWORD_HERE

To your actual password:

- CONSENSUS_KEY_PWD=your_secure_password

5. Verify required files

Before starting the container, verify all required files are present:

tree .

You should see:

.
├── bin
│   └── VERSION
├── docker-compose.yml
├── genesis.conf
└── pharos.conf

Required files:

• genesis.conf - Genesis configuration
• pharos.conf - Node configuration
• docker-compose.yml - Docker Compose configuration with your password
• bin/VERSION - Network version information

Missing files? Go back to steps 2-4 to download and configure them.

6. Start the node

Start the Pharos node with Docker Compose:

docker compose up -d

7. Check node status

View logs:

docker compose logs -f pharos

Check if the node is running:

docker compose ps

You should see:

NAME          IMAGE                                                                         STATUS         PORTS
pharos-node   public.ecr.aws/k2g7b7g1/pharos:pharos_community_v0.15.0_d6d98fd3_0720         Up 2 minutes   0.0.0.0:18100->18100/tcp, ...

Check node health:

curl http://localhost:18100

Managing the node

Stop the node

docker compose stop

Restart the node

docker compose restart

Stop and remove the container

docker compose down

Note: This does not delete your data. Data is persisted in /data/pharos/.

View real-time logs

docker compose logs -f

Execute commands in the container

docker compose exec pharos bash

Directory Structure

After deployment, your directory structure will look like:

/data/pharos/
├── bin/                   # Auto-copied from image on each start
│   ├── pharos_light
│   ├── pharos_cli
│   └── VERSION
├── ops                    # Auto-copied from image on each start
├── keys/                  # Auto-generated on first start
│   ├── domain.key
│   ├── domain.pub
│   ├── stabilizing.key
│   └── stabilizing.pub
├── data/                  # Created after bootstrap
│   └── meta_store/
├── log/
│   ├── aldaba.log
│   ├── aldaba_cli.log
│   └── pamir.log
├── genesis.conf           # Downloaded in step 2
├── pharos.conf            # Downloaded in step 2
└── docker-compose.yml     # Created in step 3, edited in step 4

Upgrading the node

To upgrade to a new version, update the image tag in docker-compose.yml to the new version, then:

# Pull the new image
docker compose pull

# Restart with new image
docker compose up -d

Security Recommendations

1. Use strong passwords: Set a secure password for CONSENSUS_KEY_PWD
2. Protect your keys: Ensure /data/pharos/keys/ has proper permissions
3. Firewall configuration: Only expose necessary ports
4. Regular backups: Backup /data/pharos/keys/ and pharos.conf
5. Keep updated: Regularly pull and update to the latest image
6. Monitor logs: Regularly check logs for errors or warnings

Next Steps

• Node Monitoring Setup - Configure Prometheus metrics for your node