Saltar a contenido

Taller S01 — Instalar Windows, WSL2, Ubuntu, Docker, DDEV, VS Code y primera instalación de Drupal

Objetivo

Preparar desde cero un equipo Windows para trabajar en Drupal Academy con una única configuración:

Windows
└── WSL2
    └── Ubuntu 24.04
        └── Docker Engine (Docker CE)
            └── DDEV

VS Code (Windows) ── extensión WSL ──> archivos y terminal de Ubuntu

Al terminar, Docker y DDEV funcionarán dentro de Ubuntu. VS Code estará instalado en Windows, pero abrirá y ejecutará el proyecto dentro de Ubuntu mediante WSL.

Importante: este manual tiene una sola ruta. No instales Docker Desktop y no mezcles estas instrucciones con otro método de instalación de DDEV.

0. Requisitos previos

  • Windows 10 versión 2004 o posterior, o Windows 11.
  • Virtualización activada en BIOS/UEFI.
  • Conexión a Internet.
  • Al menos 8 GB de RAM y espacio libre para Ubuntu, Docker y los proyectos.
  • Permisos de administrador en Windows.

Durante el manual se utilizan dos terminales diferentes:

  • PowerShell como administrador: comandos que empiezan por wsl.
  • Ubuntu: comandos que empiezan por sudo, docker, ddev o code.

No ejecutes comandos de Ubuntu en PowerShell ni comandos de PowerShell en Ubuntu.

1. Instalar WSL2 en Windows

Abre PowerShell como administrador desde el menú Inicio y ejecuta:

wsl --install --no-distribution

Reinicia Windows si lo solicita. Después de reiniciar, actualiza WSL:

wsl --update

Comprueba el estado:

wsl --status

Debe indicar que la versión predeterminada es WSL2 o que WSL2 está disponible.

2. Instalar Ubuntu 24.04 dentro de WSL

En la misma ventana de PowerShell como administrador, ejecuta:

wsl --install -d Ubuntu-24.04

Cuando termine:

  1. Abre Ubuntu 24.04 desde el menú Inicio.
  2. Espera a que finalice la preparación inicial.
  3. Escribe un nombre de usuario Linux en minúsculas.
  4. Escribe una contraseña y repítela.

Al escribir la contraseña no aparecerán caracteres en pantalla; es normal.

En Ubuntu, comprueba que la distribución es correcta:

cat /etc/os-release

Debe aparecer Ubuntu 24.04.

Ahora vuelve a PowerShell y confirma que Ubuntu utiliza WSL2:

wsl --list --verbose

La columna VERSION de Ubuntu-24.04 debe mostrar 2. Si muestra 1, ejecuta en PowerShell:

wsl --set-version Ubuntu-24.04 2

3. Activar systemd en Ubuntu

Docker necesita un servicio que se inicie correctamente. Lo configuraremos mediante systemd, que está soportado por WSL2.

En Ubuntu, ejecuta:

sudo nano /etc/wsl.conf

Escribe exactamente estas líneas:

[boot]
systemd=true

Guarda con Ctrl+O, pulsa Enter y sal con Ctrl+X.

Después, en PowerShell, reinicia completamente WSL:

wsl --shutdown

Vuelve a abrir Ubuntu desde el menú Inicio y comprueba systemd:

ps -p 1 -o comm=

El resultado esperado es systemd.

4. Actualizar Ubuntu e instalar dependencias

Todos los comandos siguientes se ejecutan en Ubuntu:

sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg

5. Instalar Docker Engine (Docker CE)

5.1 Añadir el repositorio oficial de Docker

En Ubuntu, elimina paquetes antiguos que podrían entrar en conflicto:

sudo apt remove -y docker.io docker-doc docker-compose podman-docker containerd runc 2>/dev/null || true

Añade la clave del repositorio oficial:

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Configura el repositorio para la versión de Ubuntu instalada:

echo \
  "Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "\${UBUNTU_CODENAME:-\$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc" | \
  sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null

5.2 Instalar Docker

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

5.3 Permitir usar Docker sin sudo

Activa el servicio y añade tu usuario al grupo docker:

sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

Cierra la ventana de Ubuntu y vuelve a abrirla para que el cambio de grupo tenga efecto. Después comprueba Docker:

docker version
docker compose version
docker buildx version
docker run hello-world

La última orden debe mostrar el mensaje de bienvenida de Docker. A partir de ahora, no uses sudo con docker ni con ddev.

6. Instalar DDEV en Ubuntu

DDEV se instalará dentro de Ubuntu desde su repositorio oficial de paquetes.

En Ubuntu, ejecuta el bloque completo:

sudo true
sudo apt update && sudo apt install -y curl
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://packages.ddev.com/public/gpg.key | sudo tee /etc/apt/keyrings/ddev.asc > /dev/null
sudo chmod a+r /etc/apt/keyrings/ddev.asc
sudo rm -f /etc/apt/keyrings/ddev.gpg /etc/apt/sources.list.d/ddev.list
printf "Types: deb\\nURIs: https://packages.ddev.com/public/deb/ubuntu\\nSuites: stable\\nComponents: main\\nSigned-By: /etc/apt/keyrings/ddev.asc\\n" | sudo tee /etc/apt/sources.list.d/ddev.sources > /dev/null
sudo apt update
sudo apt install -y ddev

Inicializa los certificados locales que utiliza DDEV:

mkcert -install

Comprueba la instalación:

ddev version
ddev utility tls-diagnose

Si ddev version responde con la versión instalada, DDEV está listo.

7. Instalar VS Code en Windows

Este paso se realiza en Windows, no dentro de Ubuntu.

  1. Descarga Visual Studio Code para Windows.
  2. Ejecuta el instalador.
  3. Acepta añadir VS Code al PATH si el instalador muestra esa opción.
  4. Abre VS Code.
  5. En Extensions, busca e instala WSL de Microsoft (ms-vscode-remote.remote-wsl).

La extensión Docker es opcional. No sustituye a Docker Engine y no es necesaria para trabajar con DDEV.

8. Conectar VS Code de Windows con Ubuntu

En Ubuntu, crea la carpeta de proyectos dentro del sistema de archivos Linux:

mkdir -p ~/proyectos
cd ~/proyectos

No guardes los proyectos habituales en /mnt/c/. DDEV recomienda trabajar dentro de la distribución WSL2 porque ofrece mejor rendimiento y evita problemas de permisos.

Desde Ubuntu, comprueba que VS Code está disponible:

code --version

Abre la carpeta actual en VS Code:

code .

La ventana de VS Code debe mostrar WSL: Ubuntu en la esquina inferior izquierda. Eso confirma que VS Code está ejecutándose en Windows, pero la terminal, las extensiones Linux y los archivos están conectados a Ubuntu.

9. Crear el proyecto Drupal CMS con DDEV

Seguiremos el quickstart oficial de DDEV para Drupal CMS. El nombre del proyecto será site01.

En Ubuntu, crea la carpeta del proyecto y entra en ella:

mkdir -p ~/proyectos/site01
cd ~/proyectos/site01

Configura DDEV con el tipo de proyecto drupal11 y el directorio público web:

ddev config --project-type=drupal11 --docroot=web

Arranca DDEV. La primera vez puede tardar unos minutos mientras descarga las imágenes necesarias:

ddev start

Instala Drupal CMS mediante Composer:

ddev composer create-project drupal/cms

Desempaqueta la receta de instalación de Drupal CMS:

ddev composer drupal:recipe-unpack

Abre el instalador web de Drupal CMS:

ddev launch

Completa el asistente en el navegador. Cuando solicite los datos de la base de datos, DDEV ya ha preparado la configuración del proyecto. Para consultar la URL y el estado del entorno puedes usar:

ddev describe
ddev status

Lista de comprobación

  • [ ] wsl --list --verbose muestra Ubuntu-24.04 con versión 2.
  • [ ] ps -p 1 -o comm= muestra systemd en Ubuntu.
  • [ ] docker version funciona sin sudo.
  • [ ] docker run hello-world termina correctamente.
  • [ ] docker compose version funciona.
  • [ ] ddev version funciona sin sudo.
  • [ ] VS Code muestra WSL: Ubuntu.
  • [ ] El proyecto está dentro de ~/proyectos, no en /mnt/c/.
  • [ ] ddev describe muestra la URL del proyecto Drupal.

Problemas frecuentes

wsl --install no funciona

Actualiza Windows, reinicia el equipo y vuelve a ejecutar PowerShell como administrador. Comprueba también que la virtualización está activada en BIOS/UEFI.

Ubuntu aparece con versión 1

En PowerShell ejecuta:

wsl --set-version Ubuntu-24.04 2

docker: permission denied

Cierra todas las ventanas de Ubuntu y vuelve a abrirlas después de ejecutar:

sudo usermod -aG docker "$USER"

docker no está activo

En Ubuntu ejecuta:

sudo systemctl start docker
sudo systemctl status docker

Si systemd no está activo, repite el paso 3 y ejecuta wsl --shutdown desde PowerShell.

ddev no se encuentra

Cierra y vuelve a abrir Ubuntu. Si continúa el problema, comprueba que el bloque de instalación de DDEV terminó sin errores y ejecuta sudo apt update antes de repetir sudo apt install -y ddev.

VS Code no muestra WSL: Ubuntu

Cierra la ventana actual. Desde Ubuntu, entra en la carpeta del proyecto y ejecuta:

code .

Comprueba que la extensión WSL de Microsoft está instalada en VS Code para Windows.

El proyecto está en /mnt/c/

Muévelo a Ubuntu:

mkdir -p ~/proyectos
mv /mnt/c/ruta/al/proyecto ~/proyectos/

Referencias oficiales