Documentación — Instalación Correcta de Docker + Portainer

Este documento resume el proceso completo de diagnóstico, identificación del problema y reinstalación estable de Docker Engine, Docker Compose y Portainer CE en un servidor con HestiaCP, para resolver los errores de conexión del entorno local en Portainer.

Problema detectado

El usuario experimentaba errores constantes en Portainer al intentar acceder al entorno local:

El entorno aparecía como Up → Down → Up → Down repetidamente.
Error recurrente: Failed loading environment — The environment named local is unreachable.
Portainer no lograba conectarse al socket /var/run/docker.sock.

Esto hacía imposible gestionar contenedores o stacks, incluso después de reinstalar Portainer repetidas veces.

Causas identificadas

Tras depurar el sistema, se identificaron las siguientes causas:

Docker Engine estaba corrupto debido a instalaciones previas incompletas.
Repositorios de Docker dañados en /etc/apt/sources.list.d/.
Versiones incompatibles:
- Docker 29.0.0
- Portainer CE 2.33.3
El socket /var/run/docker.sock se caía intermitentemente.
HestiaCP no era el problema (simplemente coexistía con Docker).

Solución aplicada

Se realizó una reinstalación completa, limpia y controlada de todo el ecosistema Docker:

Eliminación total de Docker, Docker Compose y Portainer.
Remoción de imágenes, contenedores, volúmenes y binarios.
Corrección manual de claves GPG y repositorios defectuosos.
Instalación limpia de versiones compatibles y estables.

Versiones instaladas correctamente

Docker Engine: 27.5.1
Docker Compose Plugin: v2.40.3
Docker Compose (binario independiente): v2.23.0
Portainer CE: 2.19.5

Procedimiento técnico aplicado

1. Eliminación completa:

# Detener servicios
systemctl stop docker || true

# Remover Docker y Portainer
apt purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
rm -rf /var/lib/docker /var/lib/containerd
rm -rf /etc/docker /etc/apt/sources.list.d/docker.list

# Eliminar Portainer
docker rm -f portainer || true
docker volume rm portainer_data || true

2. Reinstalar repositorios oficiales:

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor \
  -o /etc/apt/keyrings/docker.gpg

echo \
"deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list

3. Instalar Docker Engine estable:

apt update
apt install -y docker-ce=5:27.5.1-1~ubuntu.22.04~jammy \
               docker-ce-cli \
               containerd.io \
               docker-buildx-plugin \
               docker-compose-plugin

systemctl enable docker
systemctl start docker

4. Instalar Docker Compose (binario independiente):

curl -SL https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-linux-x86_64 \
  -o /usr/local/bin/docker-compose

chmod +x /usr/local/bin/docker-compose

5. Instalar Portainer CE 2.19.5:

docker volume create portainer_data

docker run -d \
  -p 9443:9443 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:2.19.5

Resultado final

Portainer pudo conectarse sin errores al entorno local mediante /var/run/docker.sock, mostrando correctamente el estado del servidor, contenedor activo y recursos disponibles.

El problema quedó completamente resuelto.

Regresar