Antes de instalar servicios como Home Assistant, Portainer o Grafana, necesitamos una base sólida: una Raspberry Pi preparada, acceso remoto, Docker instalado y una estructura ordenada para nuestros proyectos.
En esta guía vamos a preparar una Raspberry Pi paso a paso, desde la instalación de Raspberry Pi OS hasta la primera prueba de Docker. No necesitas experiencia previa con Linux: explicaremos qué hace cada comando y cómo comprobar que todo funciona.
¿Qué vamos a conseguir?
- Raspberry Pi OS de 64 bits instalado y actualizado.
- Un usuario propio y acceso por SSH desde otro ordenador.
- Una dirección IP configurada para tu red.
- Docker Engine y Docker Compose instalados.
- Una prueba de ejecución de un contenedor completada correctamente.
- Una estructura de carpetas preparada para los siguientes tutoriales.
Importante: este tutorial está pensado para una Raspberry Pi 5 con arquitectura ARM64 y Raspberry Pi OS de 64 bits. Los nombres de red, las direcciones IP y las contraseñas de los ejemplos son ficticios: tendrás que adaptarlos a tu instalación.
1. Preparar el hardware y el almacenamiento
Para seguir la guía utilizaremos una Raspberry Pi 5 con 16 GB de RAM y un NVMe de 250 GB.
Puedes instalar Raspberry Pi OS en una tarjeta microSD, un SSD USB o un NVMe compatible. Para un servidor que permanecerá encendido muchas horas, un SSD o NVMe es una buena opción, siempre que el adaptador o la placa de expansión sean compatibles con tu Raspberry Pi.
Antes de comenzar, comprueba que tienes:
- Una Raspberry Pi y su fuente de alimentación adecuada.
- Un NVMe o dispositivo de almacenamiento compatible.
- Un cable Ethernet.
- Un ordenador con Windows, Linux o macOS.
- Acceso al router para consultar la red y elegir una dirección IP válida.
¿Qué debemos saber sobre el NVMe?
El NVMe es el dispositivo donde se almacenará el sistema operativo y, más adelante, los datos de nuestros servicios. No basta con disponer de una unidad: también necesitamos una forma compatible de escribir la imagen del sistema y arrancar desde ella.
Si el NVMe no se puede conectar directamente al ordenador, necesitaremos un adaptador compatible o un método alternativo de instalación. No continúes hasta saber qué unidad vas a utilizar.
Precaución: el proceso de grabación elimina los datos del dispositivo de destino. Verifica siempre que has seleccionado la unidad correcta.
2. Instalar Raspberry Pi OS con Raspberry Pi Imager
Raspberry Pi Imager es la herramienta oficial que permite seleccionar el modelo de Raspberry Pi, descargar el sistema operativo y prepararlo en el almacenamiento.
Descárgala desde la página oficial: Raspberry Pi Imager.
Instala la aplicación y ábrela.
Paso 1. Elegir el dispositivo
Selecciona el modelo de Raspberry Pi que vas a utilizar. En nuestro caso, una Raspberry Pi 5.
Paso 2. Elegir el sistema operativo
Selecciona Raspberry Pi OS (64-bit) con escritorio. Es la versión definida para esta guía y permite utilizar la Raspberry Pi tanto con pantalla como mediante SSH. Raspberry Pi OS Lite también puede ser una alternativa para un servidor sin escritorio, pero aquí seguiremos con la versión de escritorio.
Paso 3. Seleccionar el almacenamiento
Elige el NVMe o el dispositivo compatible donde instalarás el sistema. Comprueba la capacidad y asegúrate de que no estás seleccionando el disco del ordenador.
Paso 4. Personalizar la instalación
Cuando Imager te ofrezca la personalización del sistema, configura estos valores:
- Nombre del equipo: utiliza un nombre sencillo, por ejemplo,
pi-docker. - Usuario: crea un usuario propio. No dependas de credenciales predeterminadas.
- Contraseña: establece una contraseña única y robusta.
- Zona horaria y teclado: selecciona los valores que correspondan a tu ubicación.
- SSH: activa el acceso remoto y selecciona la autenticación mediante contraseña para seguir esta primera guía.
No compartas capturas que muestren la contraseña. El nombre pi-docker es solo un ejemplo y puedes escoger otro.
Paso 5. Grabar y verificar
Guarda la personalización y confirma la escritura. Espera a que Imager termine tanto la grabación como la verificación.
Cuando finalice, conecta el almacenamiento preparado y enciende la Raspberry Pi.
La documentación oficial explica estos pasos y las opciones de personalización de Imager: primeros pasos con Raspberry Pi.
3. Arrancar la Raspberry Pi y configurar la red
Conecta el cable Ethernet al router o switch y enciende la Raspberry Pi. Espera a que termine el primer arranque.
Para conectarnos desde otro ordenador necesitamos conocer la dirección IP de la Raspberry Pi. Podemos consultarla desde la configuración de red del propio sistema o desde el router.
Configurar la dirección IP
Antes de introducir los valores, identifica en tu red:
- Dirección IP: la dirección que tendrá la Raspberry Pi.
- Máscara o prefijo de red: indica qué direcciones pertenecen a la red local.
- Puerta de enlace: normalmente es la dirección del router.
- DNS: el servidor que resuelve los nombres de dominio.
Los valores deben corresponder a tu propia red. No copies una dirección de ejemplo sin comprobar que es válida y que no está asignada a otro dispositivo.
Desde el entorno gráfico de Raspberry Pi OS, abre la configuración de red y busca las opciones IPv4 de la conexión Ethernet. Selecciona la configuración manual e introduce los valores que hayas comprobado. Los nombres exactos de los menús pueden variar según la versión del sistema y el gestor de red utilizado.
Guarda los cambios y comprueba que sigues teniendo conectividad. Si pierdes la conexión, utiliza la pantalla y el teclado conectados directamente a la Raspberry Pi para revisar la configuración.
Consejo: anota la dirección que hayas elegido. La utilizaremos para conectarnos por SSH y administrar el equipo.
4. Conectarse por SSH desde otro ordenador
SSH significa Secure Shell. Es un protocolo que permite abrir una terminal de forma remota y ejecutar comandos en otro equipo.
Como hemos activado SSH durante la personalización de Imager, ya podemos intentar la conexión. Sustituye usuario y IP_DE_LA_RASPBERRY por los valores de tu instalación.
Windows
Abre Windows Terminal o PowerShell y ejecuta:
ssh usuario@IP_DE_LA_RASPBERRYPor ejemplo, con datos ficticios:
ssh pi-docker@192.0.2.10La dirección 192.0.2.10 pertenece a un rango reservado para documentación y no debe utilizarse como dirección real de tu red.
La primera vez puede aparecer una pregunta sobre la autenticidad del servidor. Comprueba que estás conectándote a tu Raspberry Pi antes de aceptar. Después introduce la contraseña del usuario que creaste. Mientras escribes la contraseña, es normal que no aparezcan caracteres en pantalla.
Linux y macOS
Abre la terminal y utiliza el mismo formato:
ssh usuario@IP_DE_LA_RASPBERRYUna vez autenticado, aparecerá una línea de comandos correspondiente a la Raspberry Pi. Desde ese momento, los comandos que escribas se ejecutarán en el equipo remoto, no en tu ordenador.
Si la conexión falla
- Comprueba que la Raspberry Pi está encendida.
- Comprueba que el cable de red está conectado.
- Verifica que la dirección IP es correcta.
- Confirma que SSH está activado.
- Comprueba el usuario y la contraseña.
Si aparece Connection refused, puede que el servicio SSH no esté activo. Si aparece Connection timed out, revisa primero la conectividad y la dirección IP.
Consulta también la documentación oficial sobre acceso remoto de Raspberry Pi.
5. Actualizar Raspberry Pi OS
Antes de instalar Docker, conviene actualizar la lista de paquetes y aplicar las actualizaciones disponibles.
sudo apt update
sudo apt full-upgradeEl primer comando consulta los repositorios y actualiza la información de los paquetes disponibles. El segundo instala las actualizaciones correspondientes y puede solicitar confirmación.
Si te pregunta si deseas continuar, revisa el resumen y confirma cuando estés seguro. No interrumpas el proceso mientras se estén instalando paquetes.
Cuando termine, reinicia si el sistema lo recomienda o si se han actualizado componentes que lo requieren:
sudo rebootLa conexión SSH se cerrará al reiniciarse el equipo. Espera a que vuelva a arrancar y conéctate de nuevo.
Comprobar la arquitectura
Ejecuta:
uname -m
dpkg --print-architectureEn nuestro entorno de referencia esperamos aarch64 en el primer comando y arm64 en el segundo. Si los resultados son diferentes, no continúes con las instrucciones de instalación de Docker para ARM64 hasta identificar qué sistema operativo y arquitectura estás utilizando.
6. Instalar Docker Engine y Docker Compose
Docker permite ejecutar aplicaciones en contenedores. Un contenedor empaqueta una aplicación y los componentes que necesita para ejecutarse de una forma aislada del resto del sistema.
Docker Engine es el servicio que administra los contenedores. Docker Compose permite describir y gestionar aplicaciones mediante un archivo de configuración. Aprenderemos a escribir ese archivo en el Tutorial 3.
Para esta guía utilizaremos el repositorio oficial de Docker compatible con Debian y ARM64. Raspberry Pi OS está basado en Debian, pero antes de instalar debemos comprobar el nombre en clave de la versión y la arquitectura.
Paso 1. Instalar las herramientas necesarias
sudo apt update
sudo apt install ca-certificates curlca-certificates permite verificar certificados TLS y curl nos permitirá descargar la clave pública del repositorio oficial.
Paso 2. Preparar la clave del repositorio
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.ascEstos comandos crean la carpeta destinada a las claves de los repositorios, descargan la clave oficial de Docker y permiten que APT pueda leerla.
Paso 3. Comprobar la versión y añadir el repositorio
. /etc/os-release
echo "$VERSION_CODENAME"
dpkg --print-architecturePara esta ruta esperamos una versión basada en Debian Trixie y arquitectura arm64. Si los resultados no coinciden, detente y consulta el procedimiento adecuado antes de añadir el repositorio.
Si los valores son los esperados, configura el repositorio:
sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $VERSION_CODENAME
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOFActualiza la lista de paquetes:
sudo apt updateRevisa que APT consulte download.docker.com sin errores de firma, arquitectura o versión.
Paso 4. Instalar Docker Engine y Compose
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-pluginEstos paquetes incluyen el motor de Docker, su cliente de línea de comandos, el componente de ejecución de contenedores y los complementos de Buildx y Compose.
Activa el servicio para que arranque automáticamente:
sudo systemctl enable --now dockerConsulta la documentación oficial de instalación de Docker para Debian.
Importante: estas instrucciones son para una instalación nueva y compatible. No desinstales paquetes ni elimines directorios de Docker en un equipo que ya tenga contenedores o datos importantes. Si el sistema no acepta el repositorio o los paquetes, detente y revisa el mensaje de error antes de probar otros métodos.
7. Comprobar que Docker funciona
Vamos a realizar dos comprobaciones: verificar que el servicio está activo y ejecutar un contenedor de prueba.
Paso 1. Comprobar el servicio
systemctl is-active dockerSi devuelve active, significa que el servicio está activo. Si devuelve otro resultado, no continúes con la siguiente prueba hasta revisar el estado del servicio.
Paso 2. Comprobar Docker Compose
docker compose versionDebe mostrar la versión instalada de Docker Compose.
Paso 3. Ejecutar un contenedor de prueba
docker run --rm hello-worldDocker descargará la imagen hello-world si todavía no está disponible localmente. Después creará un contenedor, ejecutará la prueba y lo eliminará al finalizar.
Busca el mensaje:
Hello from Docker!Este resultado confirma que el cliente ha podido comunicarse con el servicio Docker y ejecutar el contenedor de prueba.
La opción --rm elimina el contenedor al terminar, pero no desinstala Docker ni elimina otros contenedores o servicios.
¿Y si aparece un error de permisos?
Si el comando devuelve un error parecido a permission denied, no cambies los permisos de archivos ni ejecutes comandos de reparación a ciegas.
Como comprobación temporal puedes ejecutar:
sudo docker run --rm hello-worldSi funciona con sudo pero no con tu usuario, Docker está instalado, pero todavía debemos revisar los permisos.
El grupo docker permite ejecutar comandos con privilegios muy elevados, equivalentes en la práctica a los de administrador. Añadir usuarios a ese grupo no es una decisión inocua. En esta primera guía priorizamos que entiendas el riesgo antes de decidir si quieres utilizarlo.
8. Organizar las carpetas del homelab
Antes de empezar a desplegar aplicaciones, vamos a preparar un directorio donde organizar sus configuraciones. Utilizaremos /docker como carpeta de trabajo y crearemos una subcarpeta para cada servicio o proyecto.
sudo mkdir -p /docker
sudo chown "$USER":"$USER" /docker
mkdir -p /docker/pruebaEl primer comando crea el directorio. El segundo asigna su propiedad al usuario actual. El tercero crea una carpeta para futuros archivos de prueba.
Comprueba el resultado:
ls -la /dockerLa estructura inicial será parecida a esta:
/docker/
└── prueba/En los próximos tutoriales añadiremos archivos Compose y directorios de datos cuando realmente los necesitemos. No hace falta crear ahora las carpetas de todos los servicios que instalaremos más adelante.
Importante: si ya tienes un directorio /docker con servicios funcionando, no ejecutes estos comandos para reorganizarlo sin revisar antes su contenido. La estructura que ves aquí es un ejemplo para una instalación nueva.
9. Errores frecuentes y cómo resolverlos
No puedo conectarme por SSH
Comprueba la IP, el cable de red, el estado de SSH y las credenciales. Si has cambiado la configuración de red, utiliza la pantalla y el teclado conectados a la Raspberry Pi para recuperarla.
APT no encuentra los paquetes de Docker
Comprueba la arquitectura y el nombre en clave de la distribución. Revisa que el repositorio oficial se haya añadido correctamente y que sudo apt update termine sin errores. No sustituyas automáticamente trixie por otra versión ni añadas repositorios de otra distribución.
Docker no está activo
Consulta su estado:
sudo systemctl status docker --no-pagerLee el mensaje de error antes de reiniciar el servicio o cambiar su configuración.
Docker funciona con sudo, pero no sin él
Es una cuestión de permisos. No significa necesariamente que la instalación esté rota. Puedes continuar utilizando sudo mientras decides cómo administrar el acceso.
La Raspberry Pi no tiene conectividad
Comprueba el enlace Ethernet, la configuración IPv4, la puerta de enlace y el DNS. No cambies varios valores a la vez: identifica primero qué parte de la conexión está fallando.
10. Lista de comprobación final
- ☐ Raspberry Pi OS de 64 bits está instalado y actualizado.
- ☐ Puedes conectarte a la Raspberry Pi mediante SSH.
- ☐ La dirección IP configurada corresponde a tu red.
- ☐ Docker está activo.
- ☐
docker compose versionmuestra una versión instalada. - ☐
docker run --rm hello-worldtermina correctamente. - ☐ Existe la carpeta
/dockerpara organizar los futuros proyectos.
Conclusión
En este tutorial hemos preparado el sistema operativo, el acceso remoto, la conectividad, Docker y la estructura inicial de directorios. También hemos comprobado que Docker puede ejecutar un contenedor de prueba.
En el siguiente tutorial aprenderemos los conceptos fundamentales de Docker: imágenes, contenedores, volúmenes y redes. Así entenderás qué ocurre por debajo antes de crear tu primer servicio con Docker Compose.
Siguiente tutorial: Docker desde cero: imágenes, contenedores, volúmenes y redes.