# Tutorial 1: Preparar una Raspberry Pi para Docker Compose

- Link: https://www.clhome.net/preparar-raspberry-pi-docker-compose/
- Published: 2026-10-06T10:28:04+02:00
- Author: gerard

Ruta de aprendizaje
Tutorial 1 de 14

[1](https://www.clhome.net/preparar-raspberry-pi-docker-compose/)[2](https://www.clhome.net/tutorial-2-docker-desde-cero-imagenes-contenedores-volumenes-redes/)
[3](https://www.clhome.net/tutorial-3-primer-servicio-docker-compose/)[4](https://www.clhome.net/tutorial-4-administrar-docker-portainer/)
[5](https://www.clhome.net/red-docker-macvlan-portainer/)[6](https://www.clhome.net/servicios-homelab-docker-compose-dozzle-home-assistant/)
[7](https://www.clhome.net/instalar-home-assistant-y-node-red-con-docker/)[8](https://www.clhome.net/instalar-unifi-network-application-docker-compose/)
[9](https://www.clhome.net/monitorizar-homelab-grafana-prometheus-docker/)[10](https://www.clhome.net/gestionar-actualizaciones-y-copias-de-seguridad-de-contenedores/)
[11](https://www.clhome.net/crear-un-sistema-de-comprobacion-de-salud-y-alertas-para-docker/)
[12](https://www.clhome.net/tutorial-12-proteger-docker-permisos-secretos-puertos-aislamiento/)
[13](https://www.clhome.net/tutorial-13-acceso-remoto-seguro-servicios-docker/)[14](https://www.clhome.net/tutorial-14-diagnosticar-errores-docker/)

[Índice de guías](https://www.clhome.net/guias/)[Siguiente →](https://www.clhome.net/tutorial-2-docker-desde-cero-imagenes-contenedores-volumenes-redes/)

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](https://www.raspberrypi.com/software/).

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](https://www.raspberrypi.com/documentation/computers/getting-started.html).

## 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_RASPBERRY
    ```

Por ejemplo, con datos ficticios:

    ```
    ssh pi-docker@192.0.2.10
    ```

La 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_RASPBERRY
    ```

Una 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

 1. Comprueba que la Raspberry Pi está encendida.
 2. Comprueba que el cable de red está conectado.
 3. Verifica que la dirección IP es correcta.
 4. Confirma que SSH está activado.
 5. 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](https://www.raspberrypi.com/documentation/computers/remote-access.html).

## 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-upgrade
    ```

El 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 reboot
    ```

La 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-architecture
    ```

En 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 curl
    ```

`ca-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.asc
    ```

Estos 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-architecture
    ```

Para 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
    EOF
    ```

Actualiza la lista de paquetes:

    ```
    sudo apt update
    ```

Revisa 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-plugin
    ```

Estos 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 docker
    ```

Consulta la [documentación oficial de instalación de Docker para Debian](https://docs.docker.com/engine/install/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 docker
    ```

Si 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 version
    ```

Debe mostrar la versión instalada de Docker Compose.

### Paso 3. Ejecutar un contenedor de prueba

    ```
    docker run --rm hello-world
    ```

Docker 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-world
    ```

Si 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/prueba
    ```

El 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 /docker
    ```

La 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-pager
    ```

Lee 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 version` muestra una versión instalada.
 * ☐ `docker run --rm hello-world` termina correctamente.
 * ☐ Existe la carpeta `/docker` para 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.

[Continuar con el Tutorial 2](https://www.clhome.net/tutorial-2-docker-desde-cero-imagenes-contenedores-volumenes-redes/)

[Volver al índice de guías de CLHOME](https://www.clhome.net/guias/)

## Siguiente tutorial: Docker desde cero: imágenes, contenedores, volúmenes y redes

En el tutorial 2 continuaremos la ruta de Docker y servicios paso a paso.

[Pasa al siguiente tutorial →](https://www.clhome.net/tutorial-2-docker-desde-cero-imagenes-contenedores-volumenes-redes/)