Cómo solucionar Code exited (1) en Docker en Raspberry Pi

¿Por qué ocurre este error?

El código de salida 1 indica que el proceso principal del contenedor terminó con un error genérico. En Raspberry Pi, los casos más comunes son:

• Arquitectura incompatible: La imagen fue construida para amd64 (x86_64), pero Raspberry Pi usa armhf o arm64.
• Falta de binarios compatibles: El ENTRYPOINT o CMD del contenedor intenta ejecutar un binario compilado para otra arquitectura.
• Problemas de permisos en /dev o recursos del sistema: Especialmente si el contenedor requiere acceso a GPIO, I2C, o hardware específico.
• Falta de memoria o recursos insuficientes (menos común, pero posible en Pi Zero/W).

El hecho de que funcione en una VM de Raspberry Pi (probablemente emulada en x86 con QEMU) pero no en hardware real confirma una incompatibilidad de arquitectura.

Pasos para solucionarlo

1. Verifica la arquitectura del contenedor y del host

# En tu Raspberry Pi:
uname -m
# Debería mostrar: armv7l (Pi 3/4) o aarch64 (Pi 4/5 con OS de 64 bits)

docker info --format '{{.Architecture}}'
# Debería coincidir con lo anterior

2. Verifica la arquitectura de tu imagen

docker inspect myimage --format '{{.Architecture}}'

Si muestra amd64, esa es la causa raíz.

3. Reconstruye la imagen para ARM

Opción A: Usa docker buildx (recomendado)

# Crea un builder con soporte multi-arquitectura
docker buildx create --use

# Construye e impulsa para ARM (y x86 si quieres)
docker buildx build \
  --platform linux/arm/v7,linux/amd64 \
  -t myimage:latest \
  --push \
  .

Nota: Si usas linux/arm/v7, asegúrate de que tu Pi sea compatible (Pi 2+ sí; Pi 1/Zero no).

Opción B: Construcción nativa en Pi (más lenta pero segura)

# En tu Raspberry Pi:
docker build -t myimage:arm .

4. Verifica que el binario principal sea compatible

Si no puedes reconstruir la imagen, usa qemu-user-static para emular ARM en x86 (solo para depuración):

# Instala qemu en tu máquina x86
sudo apt install qemu-user-static

# Copia el binario al contenedor y ejecuta manualmente
docker run --rm -v /usr/bin/qemu-arm-static:/usr/bin/qemu-arm-static \
  -it --entrypoint /bin/sh myimage

Luego prueba ejecutar el comando que falla.

Bloque de código corregido (ejemplo práctico)

# 1. Verifica arquitectura
uname -m && docker info --format '{{.Architecture}}'

# 2. Verifica imagen
docker inspect myimage --format '{{.Architecture}}'

# 3. Si es amd64, reconstruye para ARM (ej. Pi 3/4)
docker buildx build \
  --platform linux/arm/v7 \
  -t myimage:arm \
  .

# 4. Ejecuta sin flag `--net=host` primero para aislar el problema
docker run --rm -it myimage:arm /bin/sh

# 5. Si funciona, ejecuta con host network (pero sin `-d` para ver logs en vivo)
docker run --net=host -it myimage:arm

⚠️ Nota crítica sobre --net=host: En Raspberry Pi, no funciona en contenedores ARM si el host es x86 con QEMU, y puede causar fallos silenciosos. Usa redes bridge o --network=host solo si es estrictamente necesario y después de probar sin él.

Pro-tip: Diagnóstico rápido en 1 línea

docker run --rm -it --net=host myimage sh -c "echo 'Entrando...'; ls /bin/sh; /bin/sh -x -c 'echo OK'"

Esto te muestra si el shell funciona, si hay errores de ejecución, y te da trazas de depuración (-x).

¿Por qué falla --net=host específicamente en Pi?

• En Raspberry Pi OS (especialmente en versiones antiguas), el soporte de --net=host para contenedores ARM puede fallar si el kernel no lo permite o si hay conflictos con cgroups.
• Solución alternativa: Usa --network=host (sin espacio en =) y asegúrate de que no haya otro servicio usando el mismo puerto.

✅ Comando corregido final:

docker run --network=host -d -t myimage:arm