Objetivos
- Entender qué es un contenedor, qué es una imagen y para qué sirve un Dockerfile, sin jerga.
- Instalar Docker Desktop (o Docker Engine en Ubuntu) y comprobar que funciona con hello-world.
- Meter tu API de pe05 en un contenedor y abrirla en el navegador con docker build y docker run.
- Pasar la clave al contenedor con --env-file sin copiarla dentro de la imagen.
- Saber qué es un VPS, SSH con clave, un cortafuegos y HTTPS con Caddy, para cuando un día decidas contratar uno.
Antes de empezar: pe05 (tu API en local) y pe06 (.gitignore con .env). Unos 5 GB libres en disco para Docker Desktop.
Unidad opcional («profundiza» de la semana 4). No hace falta para seguir el itinerario. En esta unidad no contratas nada ni pagas nada: el lab se hace entero en tu ordenador. La parte de servidores es una lectura guiada para cuando llegue el momento.
Prompt de arranque
Tengo una API con FastAPI en main.py, gestionada con uv (pyproject.toml y uv.lock), que lee la clave GEMINI_API_KEY de un fichero .env. Nunca he usado Docker. Escríbeme un Dockerfile mínimo basado en python:3.12-slim que use uv para instalar las dependencias y arranque la API con "fastapi run" en el puerto 8000. Escribe también un .dockerignore que deje fuera .env y .venv. Explícame cada línea en una frase y dame los comandos docker build y docker run para probarla pasando la clave con --env-file.
Esto lo escribe la IA, tú compruebas que funciona. Abajo tienes la versión probada el 11-10-2026.
Explicación
«En mi ordenador funciona»
Es la frase más repetida en informática. Tu API funciona porque en tu ordenador hay Python 3.12, un .venv con las librerías exactas y tu .env. Llévala al portátil de otra persona o a un servidor y algo será distinto: otra versión de Python, una librería que falta, otro sistema. Docker resuelve eso metiendo tu app y todo lo que necesita en una caja que funciona igual en cualquier sitio.
Imagen, contenedor y Dockerfile, con una cocina
- El Dockerfile es la receta: un fichero de texto con los pasos (parte de una base con Python, instala estas librerías, copia este código, arranca así).
- La imagen es el plato preparado y envasado al vacío que sale de seguir la receta con
docker build. Lleva dentro todo: el sistema mínimo, Python, las librerías y tu código. No cambia. - El contenedor es ese plato servido en la mesa: la imagen en marcha, creada con
docker run. Puedes servir varios platos del mismo envase, tirarlos y servir otros: el envase sigue intacto.
Un contenedor no es un ordenador virtual completo. Comparte el núcleo del sistema con tu máquina y solo lleva lo imprescindible, por eso arranca en un segundo y ocupa poco. En Windows y macOS, Docker Desktop crea por debajo una pequeña máquina Linux donde viven los contenedores; tú no tienes que tocarla.
Puertos: la caja tiene su propia puerta
Dentro del contenedor, tu API escucha en el puerto 8000, pero ese puerto es de la caja, no de tu ordenador. Para llegar desde el navegador hay que conectar una puerta de fuera con una de dentro: -p 8000:8000 significa «el puerto 8000 de mi ordenador lleva al 8000 del contenedor». El primer número es el de fuera; el segundo, el de dentro.
Por eso, dentro del contenedor la API se arranca con fastapi run, que escucha en 0.0.0.0 (todas las puertas de la caja) y no solo en 127.0.0.1. Si escuchara solo en 127.0.0.1, únicamente la propia caja podría hablar con ella.
La clave no viaja dentro de la imagen
Una imagen se puede compartir y subir a registros públicos. Si tu .env estuviera dentro, cualquiera podría sacarlo. Por eso hacemos dos cosas: un .dockerignore que impide copiar .env a la imagen, y --env-file .env al arrancar, que entrega las variables al contenedor en marcha sin guardarlas en la imagen. Una diferencia que conviene saber: Docker lee el .env más literal que Python. Si escribiste la clave entre comillas, Docker las incluye como parte de la clave y Google la rechazará.
Qué es un VPS
Un VPS (servidor privado virtual) es un ordenador alquilado en un centro de datos, encendido día y noche, con su propia dirección en Internet. Si tu portátil es tu cocina, un VPS es un local en una calle con tráfico: ahí sí puede entrar cualquiera. Se paga por mes o por hora, y lo controlas a distancia desde tu terminal.
Precios de referencia (consultados el 11-10-2026, sin IVA; cambian a menudo, compruébalos el día que contrates):
- Hetzner (Alemania y Finlandia): el CX23 (2 vCPU, 4 GB) cuesta 5,49 €/mes más 0,50 € por la dirección IPv4, según su aviso de precios del 15-06-2026. Se cobra por horas, con tope mensual. El 11-10-2026 su web marcaba la gama más barata («Cost-Optimized») como no disponible; la siguiente gama empieza bastante más arriba.
- OVHcloud (empresa francesa): VPS-1 (2 vCore, 4 GB) desde 3,81 €/mes sin IVA, con descuento por compromiso anual.
Para aprender, un servidor así es más que suficiente. Pero recuerda: un servidor en Internet recibe visitas de robots desde el primer minuto. Por eso existen las tres piezas siguientes.
SSH con clave: la llave de tu local
SSH es la forma de abrir una terminal en el servidor desde tu ordenador. En vez de contraseña se usa una pareja de claves: la privada se queda en tu ordenador (es tu llave, nunca se comparte) y la pública se entrega al proveedor al crear el servidor (es la cerradura). Solo quien tenga la llave abre esa cerradura. Se crea con ssh-keygen -t ed25519, que funciona igual en Windows 11, macOS y Linux.
Cortafuegos: solo las puertas que necesitas
Un cortafuegos cierra todas las puertas del servidor salvo las que eliges: la 22 (SSH), la 80 (web) y la 443 (web segura). En Ubuntu se llama ufw. Hay un detalle traicionero: los puertos que publica Docker con -p se saltan ufw. Por eso, en un servidor, el contenedor se publica solo hacia dentro (-p 127.0.0.1:8000:8000) y es Caddy quien da la cara.
HTTPS con Caddy: el candado
Caddy es un servidor web que se pone delante de tu API, recibe las visitas en los puertos 80 y 443 y se las pasa a tu contenedor. Su gran ventaja: consigue y renueva solo el certificado HTTPS (el candado del navegador) con Let's Encrypt, sin coste. Necesita un nombre de dominio que apunte a la IP del servidor. Su configuración completa cabe en tres líneas.
Lab paso a paso (todo en tu ordenador, sin pagar nada)
Objetivo: tu API de pe05 funcionando dentro de un contenedor en http://127.0.0.1:8000/docs.
Paso 1. Instalar Docker
Windows 11 (PowerShell como administrador). Docker Desktop necesita WSL 2:
wsl --install
Reinicia el ordenador. Después, en PowerShell normal:
winget install -e --id Docker.DockerDesktop
macOS:
brew install --cask docker-desktop
En Windows y macOS, abre Docker Desktop desde el menú de aplicaciones y acepta las condiciones. Es gratuito para uso personal, educativo y empresas pequeñas (menos de 250 empleados y menos de 10 millones de dólares de facturación anual). Espera a que la ballena indique «Engine running».
Ubuntu (Docker Engine, sin interfaz):
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker
Comprueba en cualquier sistema:
docker run hello-world
Salida esperada (entre otras líneas): Hello from Docker! y This message shows that your installation appears to be working correctly.
Paso 2. Preparar el proyecto
En VS Code, abre ~/lab/mi-api (la API de pe05). Crea un fichero .dockerignore:
.env
.venv
.git
__pycache__
Y un fichero Dockerfile (sin extensión):
# 1. Partimos de una imagen oficial con Python 3.12 ya instalado
FROM python:3.12-slim
# 2. Traemos uv, el mismo gestor de paquetes que usas en tu ordenador
COPY --from=ghcr.io/astral-sh/uv:0.11 /uv /uvx /bin/
# 3. Carpeta de trabajo dentro del contenedor
WORKDIR /app
# 4. Primero, solo la lista de ingredientes (Docker reutiliza este paso si no cambia)
COPY pyproject.toml uv.lock ./
RUN uv sync --locked --no-install-project
# 5. Después, el código
COPY main.py ./
# 6. Arrancar la API en modo producción, escuchando en el puerto 8000
EXPOSE 8000
CMD [".venv/bin/fastapi", "run", "main.py", "--port", "8000"]
Comprueba que tu .env tiene la clave sin comillas: GEMINI_API_KEY=AQ....
Paso 3. Construir la imagen
Desde ~/lab/mi-api (igual en los tres sistemas):
docker build -t mi-api .
El punto final significa «usa la receta de esta carpeta». La primera vez tarda uno o dos minutos. Salida esperada al final: naming to docker.io/library/mi-api y DONE. Compruébalo con docker image ls mi-api: verás la imagen con unos 380 MB.
Paso 4. Arrancar el contenedor
docker run --rm --name mi-api -p 8000:8000 --env-file .env mi-api
--rm borra el contenedor al pararlo; --name le da un nombre; -p 8000:8000 conecta las puertas; --env-file .env le entrega la clave. Salida esperada:
🌐 Server started at http://0.0.0.0:8000
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
Si tienes la API de pe05 encendida fuera de Docker, párala antes: las dos quieren el puerto 8000.
Paso 5. Probarla
Abre http://127.0.0.1:8000/docs y ejecuta POST /preguntar como en pe05: Code 200 y la respuesta de Gemini. Desde otra terminal:
- macOS y Linux:
curl http://127.0.0.1:8000/saludo - Windows:
curl.exe http://127.0.0.1:8000/saludo
Salida: {"mensaje":"Hola, builder. Tu API funciona."}.
Comprueba que la clave no está dentro de la imagen:
docker exec mi-api ls -a /app
Verás .venv, main.py, pyproject.toml y uv.lock, pero **no .env**.
Paso 6. Pararlo y limpiar
Ctrl+C en la terminal del contenedor (o docker stop mi-api desde otra). Para liberar espacio cuando acabes la unidad:
docker image rm mi-apiRuta sin instalar nada: GitHub Codespaces
Los Codespaces por defecto traen Docker. Haz los pasos 2 a 5 en su terminal; al publicar el puerto 8000, VS Code ofrece Open in Browser. Consume más cuota que pe05: apaga el Codespace al terminar.
Evidencia
Captura de /docs con POST /preguntar respondiendo 200 mientras la terminal muestra el contenedor en marcha, y captura de docker exec mi-api ls -a /app sin .env.
Criterio de aceptación
Lectura guiada: cuando un día contrates un VPS
No hagas estos pasos ahora. Son el mapa para el día que decidas publicar tu API. El itinerario AI Builder (semana 4 y m17) lo trata a fondo.
- Crear la llave SSH en tu ordenador:
ssh-keygen -t ed25519 -C "mi-portatil". Pulsa Intro para la ruta por defecto y elige una frase de paso. La parte pública está en~/.ssh/id_ed25519.pub(en Windows,C:\Users\<tu usuario>\.ssh\id_ed25519.pub). - Crear el servidor en la consola del proveedor: Ubuntu 24.04, ubicación en la UE y la llave pública pegada en el apartado «SSH keys». Debe añadirse al crearlo; añadirla después es más complicado.
- Entrar:
ssh root@<IP-del-servidor>. La primera vez pregunta si confías en la huella del servidor: respondeyes. - Cortafuegos, con SSH primero para no quedarte fuera:
ufw allow OpenSSH,ufw allow 80/tcp,ufw allow 443/tcp,ufw enableyufw status. - Docker en el servidor con el mismo script del paso 1 de Ubuntu. Copiar el proyecto con
scp, construir la imagen allí y arrancarla publicada solo hacia dentro:docker run -d --name mi-api --restart unless-stopped -p 127.0.0.1:8000:8000 --env-file .env mi-api. - HTTPS con Caddy:
apt install -y caddyy un/etc/caddy/Caddyfilecon:
mi-api.tudominio.com {
reverse_proxy 127.0.0.1:8000
}
Después, systemctl reload caddy. El dominio debe apuntar ya a la IP del servidor.
- Antes de abrirla al mundo: una API pública sin protección deja que cualquiera gaste tu cuota de Gemini. Añadir protección es parte del itinerario; mientras tanto, apágala (
docker stop mi-api) y borra el servidor cuando acabes de probar, porque se sigue pagando mientras exista.
URLs de activación
Verificadas el 11-10-2026 (200 OK). Precios consultados el 11-10-2026.
Errores frecuentes
| Síntoma | Qué pasa | Cómo se arregla |
|---|---|---|
Cannot connect to the Docker daemon ... Is the docker daemon running? (Windows y macOS) | Docker Desktop no está abierto o aún está arrancando. | Ábrelo y espera a «Engine running». Repite el comando. |
permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock (Ubuntu) | Tu usuario no está en el grupo docker. | sudo usermod -aG docker $USER y cierra sesión y vuelve a entrar (o newgrp docker). |
WSL 2 installation is incomplete o Docker Desktop no arranca en Windows | Falta WSL 2 o está desactualizado. | PowerShell como administrador: wsl --install o wsl --update, y reinicia. |
Bind for 0.0.0.0:8000 failed: port is already allocated | El puerto 8000 está ocupado: tu API de pe05 fuera de Docker u otro contenedor. | Para la otra API (Ctrl+C) o docker ps y docker stop <nombre>. O usa otro puerto de fuera: -p 8001:8000 y abre http://127.0.0.1:8001. |
La API responde 401 en Docker pero funciona con fastapi dev | En .env la clave está entre comillas. Python las quita; Docker no. | Escribe GEMINI_API_KEY=AQ... sin comillas, para el contenedor y vuelve a lanzar docker run. |
docker: invalid env file (.env): variable 'GEMINI_API_KEY ' contains whitespaces | Hay espacios alrededor del =. | Déjalo como GEMINI_API_KEY=valor, sin espacios. |
ModuleNotFoundError: No module named 'google' dentro del contenedor | La imagen se construyó antes de añadir la librería, o uv.lock no está actualizado. | En tu ordenador, uv add google-genai; después repite docker build -t mi-api .. |
/bin/bash^M: bad interpreter al ejecutar un script .sh en un servidor o contenedor | El script se guardó en Windows con finales de línea CRLF. | En VS Code, cambia «CRLF» por «LF» en la barra inferior y guarda. Para el futuro: git config --global core.autocrlf input. |
ssh: ... Permission denied (publickey). (lectura guiada) | La llave pública no se añadió al crear el servidor, el usuario no es el correcto (root en Ubuntu recién creado) o usas otra llave privada. | Comprueba el usuario y prueba con ssh -i ~/.ssh/id_ed25519 root@<IP>. Si la llave nunca se añadió, lo más sencillo con un servidor nuevo es borrarlo y crearlo otra vez con la llave. |
Quiz
Cinco preguntas para comprobar que lo has entendido. Necesitas un 70 % para aprobar.