Saltar al contenido principal

Instalación con Docker

Guía para ejecutar KodeChain utilizando Docker y Docker Compose.

Requisitos Previos​

  • Docker 20.10+
  • Docker Compose 2.0+ (opcional pero recomendado)
  • 4 GB RAM mínimo
  • 50 GB espacio en disco

Instalación de Docker​

Ubuntu/Debian​

# Actualizar paquetes
sudo apt update

# Instalar dependencias
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

# Añadir clave GPG de Docker
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Añadir repositorio
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Instalar Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Añadir usuario al grupo docker
sudo usermod -aG docker $USER
newgrp docker

# Verificar
docker --version
docker compose version

macOS​

Descarga e instala Docker Desktop para Mac.

Windows​

Descarga e instala Docker Desktop para Windows.

Método 1: Docker Run (Simple)​

1. Pull de la Imagen​

docker pull kodechain/node:latest

2. Ejecutar Contenedor​

docker run -d \
  --name kodechain-node \
  -p 30303:30303/tcp \
  -p 30303:30303/udp \
  -p 8545:8545/tcp \
  -v kodechain-data:/data \
  -v kodechain-keystore:/keystore \
  --restart unless-stopped \
  kodechain/node:latest \
  --consensus dpos \
  --http-port 8545 \
  --p2p-port 30303

3. Verificar Estado​

docker ps
docker logs -f kodechain-node

4. Detener/Iniciar Nodo​

# Detener
docker stop kodechain-node

# Iniciar
docker start kodechain-node

# Reiniciar
docker restart kodechain-node

Método 2: Docker Compose (Recomendado)​

1. Crear docker-compose.yml​

version: '3.8'

services:
  kodechain-dpos:
    image: kodechain/node:latest
    container_name: kodechain-dpos
    restart: unless-stopped
    ports:
      - "30303:30303/tcp"
      - "30303:30303/udp"
      - "8545:8545/tcp"
      - "30301:30301/udp"
    volumes:
      - dpos-data:/data
      - dpos-keystore:/keystore
      - ./config-dpos.json:/config.json:ro
      - ./logs:/logs
    environment:
      - CONSENSUS_TYPE=dpos
      - NODE_ID=dpos-node-1
      - LOG_LEVEL=info
    command: --config /config.json
    networks:
      - kodechain-net
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8545/api/blockchain/status"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  kodechain-pbft:
    image: kodechain/node:latest
    container_name: kodechain-pbft
    restart: unless-stopped
    ports:
      - "30403:30303/tcp"
      - "30403:30303/udp"
      - "8645:8545/tcp"
      - "30401:30301/udp"
    volumes:
      - pbft-data:/data
      - pbft-keystore:/keystore
      - ./config-pbft.json:/config.json:ro
      - ./logs:/logs
    environment:
      - CONSENSUS_TYPE=pbft
      - NODE_ID=pbft-node-1
      - LOG_LEVEL=info
    command: --config /config.json
    networks:
      - kodechain-net
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8545/api/blockchain/status"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  dpos-data:
    driver: local
  dpos-keystore:
    driver: local
  pbft-data:
    driver: local
  pbft-keystore:
    driver: local

networks:
  kodechain-net:
    driver: bridge

2. Crear Archivos de Configuración​

config-dpos.json:

{
  "node_id": "dpos-node-docker",
  "consensus_type": "dpos",
  "network": {
    "p2p_port": 30303,
    "http_port": 8545,
    "discovery_port": 30301
  },
  "bootstrap_nodes": [
    "enode://[id]@seed1.kodechain.io:30303",
    "enode://[id]@seed2.kodechain.io:30303"
  ],
  "data_dir": "/data",
  "keystore_dir": "/keystore",
  "log_level": "info"
}

config-pbft.json:

{
  "node_id": "pbft-node-docker",
  "consensus_type": "pbft",
  "network": {
    "p2p_port": 30303,
    "http_port": 8545,
    "discovery_port": 30301
  },
  "bootstrap_nodes": [
    "enode://[id]@seed1.kodechain.io:30303",
    "enode://[id]@seed2.kodechain.io:30303"
  ],
  "data_dir": "/data",
  "keystore_dir": "/keystore",
  "log_level": "info",
  "pbft": {
    "mode": "CRITICAL_RECORDS",
    "validators": []
  }
}

3. Iniciar Servicios​

# Iniciar todos los servicios
docker compose up -d

# Iniciar solo DPoS
docker compose up -d kodechain-dpos

# Iniciar solo PBFT
docker compose up -d kodechain-pbft

# Ver logs
docker compose logs -f

# Ver logs de un servicio específico
docker compose logs -f kodechain-dpos

4. Gestión de Servicios​

# Ver estado
docker compose ps

# Detener servicios
docker compose stop

# Reiniciar servicios
docker compose restart

# Detener y eliminar
docker compose down

# Detener y eliminar incluyendo volúmenes
docker compose down -v

Construir Imagen Personalizada​

1. Crear Dockerfile​

FROM golang:1.24-alpine AS builder

# Instalar dependencias
RUN apk add --no-cache git make build-base

# Establecer directorio de trabajo
WORKDIR /build

# Copiar archivos
COPY go.mod go.sum ./
RUN go mod download

COPY . .

# Compilar
RUN go build -o kodechain -ldflags="-w -s" main.go

# Imagen final
FROM alpine:latest

RUN apk add --no-cache ca-certificates curl

WORKDIR /app

# Copiar binario desde builder
COPY --from=builder /build/kodechain .

# Crear directorios
RUN mkdir -p /data /keystore /logs

# Exponer puertos
EXPOSE 30303/tcp 30303/udp 8545/tcp 30301/udp

# Ejecutar
ENTRYPOINT ["./kodechain"]
CMD ["--help"]

2. Construir Imagen​

docker build -t kodechain/node:custom .

3. Usar Imagen Custom​

Actualiza docker-compose.yml:

services:
  kodechain-dpos:
    image: kodechain/node:custom
    # ... resto de configuración

Configuración Avanzada​

Docker con Recursos Limitados​

services:
  kodechain-dpos:
    # ... configuración existente
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

Logging Avanzado​

services:
  kodechain-dpos:
    # ... configuración existente
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "5"

Network Mode Host (mejor performance)​

services:
  kodechain-dpos:
    # ... configuración existente
    network_mode: host
    # Comentar ports cuando uses host mode

Monitoreo con Docker​

Ver Recursos Usados​

docker stats kodechain-node

Inspeccionar Contenedor​

docker inspect kodechain-node

Ejecutar Comandos en Contenedor​

# Shell interactivo
docker exec -it kodechain-node sh

# Comando único
docker exec kodechain-node curl http://localhost:8545/api/blockchain/status

Stack con Monitoreo (Prometheus + Grafana)​

docker-compose.monitoring.yml:

version: '3.8'

services:
  kodechain:
    image: kodechain/node:latest
    # ... configuración básica

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus-data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
    networks:
      - kodechain-net

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    volumes:
      - grafana-data:/var/lib/grafana
      - ./grafana/provisioning:/etc/grafana/provisioning
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    networks:
      - kodechain-net

volumes:
  prometheus-data:
  grafana-data:

Backup y Restauración​

Backup de Volúmenes​

# Backup de datos
docker run --rm \
  -v kodechain-data:/data \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/kodechain-data-$(date +%Y%m%d).tar.gz -C /data .

# Backup de keystore
docker run --rm \
  -v kodechain-keystore:/keystore \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/kodechain-keystore-$(date +%Y%m%d).tar.gz -C /keystore .

Restaurar desde Backup​

# Restaurar datos
docker run --rm \
  -v kodechain-data:/data \
  -v $(pwd)/backups:/backup \
  alpine sh -c "cd /data && tar xzf /backup/kodechain-data-20250101.tar.gz"

# Restaurar keystore
docker run --rm \
  -v kodechain-keystore:/keystore \
  -v $(pwd)/backups:/backup \
  alpine sh -c "cd /keystore && tar xzf /backup/kodechain-keystore-20250101.tar.gz"

Solución de Problemas​

Contenedor no inicia​

# Ver logs detallados
docker logs kodechain-node

# Verificar configuración
docker inspect kodechain-node

Problemas de red​

# Verificar networks
docker network ls
docker network inspect kodechain-net

# Recrear network
docker network rm kodechain-net
docker network create kodechain-net

Limpiar recursos​

# Limpiar contenedores detenidos
docker container prune

# Limpiar imágenes no usadas
docker image prune

# Limpiar todo (CUIDADO)
docker system prune -a

Próximos Pasos​

  1. 🔑 Genera tus claves de validador
  2. 💰 Haz stake de 10 KDC
  3. 📊 Configura monitoreo

Instalación con Docker completada ✅