🐳 Comandos Esenciales de Docker para PreTeXt

Este post recopila los comandos más útiles de Docker que probablemente necesitarás al trabajar con imágenes y contenedores para PreTeXt.
Sirve como una chuleta rápida (cheat sheet) para escribir, compilar y servir libros desde un entorno aislado.

💡 Antes de usar el clip ▶️ o ejecutar cualquier comando de compilación, asegúrate de que Docker Desktop (Docker Engine) esté levantado y en ejecución. Sin el motor activo, los contenedores no podrán iniciarse y los procesos de construcción fallarán.

📦 1. Ver imágenes disponibles

docker images

Lista todas las imágenes que tienes en tu máquina.

🚮 2. Eliminar imágenes

Eliminar una imagen específica:

docker rmi <IMAGE_ID>

Forzar la eliminación si está en uso:

docker rmi -f <IMAGE_ID>

Eliminar imágenes no usadas:

docker image prune -a

🛑 3. Manejar contenedores

Listar contenedores activos:

docker ps

Listar todos (incluyendo detenidos):

docker ps -a

Detener un contenedor:

docker stop <CONTAINER_ID>

Eliminar un contenedor:

docker rm <CONTAINER_ID>

🔄 4. Salir y reanudar un contenedor

Cuando entras a un contenedor con docker run -it ... bash, tienes tres escenarios:

• Salir con exit o Ctrl+D
  El contenedor se detiene pero no se borra.
  Para retomarlo donde quedó:

  docker start -ai <CONTAINER_ID>
  

• Detenerlo con docker stop
  Igual que arriba: queda detenido y puedes retomarlo con docker start -ai.

• Eliminarlo con docker rm
  Se borra por completo. Si lo necesitas otra vez, deberás crear uno nuevo con docker run.

👉 Consejo: reutiliza contenedores con docker start -ai en lugar de correr docker run cada vez. Así evitas acumular decenas de contenedores innecesarios.

🏗️ 5. Construir imágenes

Por defecto, Docker busca un archivo llamado Dockerfile en el directorio actual.

Construir desde un Dockerfile llamado exactamente Dockerfile en el directorio actual:

docker build -t pretext-es-web .

Si tu archivo tiene un nombre diferente (ejemplo Dockerfile.curso, Dockerfile.latex), debes usar la opción -f para indicarlo explícitamente.

docker build -t pretext-es-web -f Dockerfile.curso .

▶️ 6. Ejecutar contenedores

Ejecutar de forma interactiva:

docker run -it -v ${PWD}:/workspace pretext-es-web bash

Ejecutar mapeando un puerto (para ver el libro en el navegador):

docker run -it -p 8080:8080 -v ${PWD}:/workspace pretext-es-web bash

🌐 7. Servir un proyecto

Dentro del contenedor:

cd /workspace/new-pretext-project/output/web
python3 -m http.server 8080 --bind 0.0.0.0

Y en tu navegador: 👉 http://localhost:8080

📚 8. Tips para MetaLibros

• Volúmenes montados: usa -v ${PWD}:/workspace para que los cambios en tu máquina se vean dentro del contenedor.
• Persistencia: si quieres mantener un contenedor “de trabajo” con dependencias listas, no lo borres; solo deténlo y retómalo con docker start -ai.
• Backups: guarda tu carpeta de proyectos (/workspace) en Git o en otro repositorio, así puedes reconstruir la imagen sin perder nada.
• Aislamiento: cada libro o proyecto puede correr en su propio contenedor, pero no repitas imágenes: compártelas con -v.

💾 9. Respaldar y restaurar imágenes

Respaldar una imagen en un archivo .tar (ejemplo en Windows con disco externo M:):

docker save -o "M:\Respaldo_Docker\pretext-cli.tar" pretext-cli:latest

Restaurar la imagen desde el respaldo:

docker load -i "M:\Respaldo_Docker\pretext-cli.tar"

👉 Esto es útil para mover imágenes grandes (ej. 9 GB) entre equipos o hacer backups en SSD externos.

🔁 10. Reingresar a un contenedor detenido

Si saliste con exit o lo detuviste con docker stop, el contenedor queda detenido pero no se borra.
Para volver a entrar en el mismo estado:

docker ps -a            # listar contenedores (incluye los detenidos)
docker start -ai <ID>   # reanudar y entrar en modo interactivo

👉 Usa docker start -ai en lugar de crear contenedores nuevos con docker run, así mantienes tu entorno de trabajo.

💽 11. Recuperar la imagen tar y usarla en tu directorio de trabajo

Si ya cargaste la imagen desde tu archivo .tar:

docker load -i "M:\Respaldo_Docker\pretext-cli.tar"

Ahora puedes crear un nuevo contenedor montando tu carpeta de proyectos (${PWD} en Linux/Mac o %cd% en Windows PowerShell) al directorio de trabajo /workspace del contenedor:

docker run -it -v ${PWD}:/workspace pretext-cli:latest bash     # Linux, a veces funciona en PS
docker run -it -v ${PWD}.Path:/workspace pretext-cli:latest bash   # forma correcta en PowerShell

👉 Si ya tenías un contenedor previo detenido, recuerda que puedes retomarlo directamente con:

docker start -ai <CONTAINER_ID>

🧹 12. Conocer el espacio ocupado por las imagenes, contenedores y otros de Docker

📊 Antes de limpiar, revisa el espacio usado y simulación de limpieza

Ver el espacio ocupado por Docker y cuánto se podría liberar:

docker system df

Simular lo que borraría docker system prune sin ejecutar nada:

docker system prune -a --volumes --dry-run

Si quieres simular solo imágenes:

docker image prune -a --dry-run

O solo volúmenes:

docker volume prune --dry-run

⚠️ Consejo: siempre revisa con –dry-run antes de una limpieza total. docker volume prune –dry-run

✅ Estrategia segura: marcar las imágenes a conservar

Antes de limpiar, crea contenedores “dummy” que se paren inmediatamente pero que mantengan vivas las imágenes asociadas:

docker run --name keep-pretext-curso pretext-curso true
docker run --name keep-ubuntu ubuntu true
docker run --name keep-hello hello-world

Estos contenedores se ejecutan una vez y se detienen, pero sirven para proteger las imágenes.

🧽 13. Ahora sí, limpieza profunda ejecutar el comando prune

Con las imágenes protegidas, puedes limpiar sin riesgo:

docker system prune -a --volumes -f

Esto borra:

• Contenedores que no uses
• Imágenes sin contenedores asociados
• Cachés y capas intermedias
• Redes no usadas
• Volúmenes huérfanos

👉 Es decir, si no las proteges preciamente, podrías perder imágenes que quieres conservar.

🗑️ Eliminar los contenedores dummy

Si ya no quieres mantener los contenedores de protección:

docker rm keep-pretext-curso keep-ubuntu keep-hello

👉 Las imágenes se conservarán aunque borres estos contenedores.

✅ Con esta técnica puedes hacer una limpieza total de tu sistema Docker sin preocuparte de borrar accidentalmente las imágenes clave de tu flujo de trabajo.

🧹 14. Si quieres limpiar todo lo no usado (opcional y potente)

docker system prune -a

⚠️ Elimina imágenes, contenedores, redes y cachés no usadas. Úsalo con cuidado.

🐳 Paso 15: Verificación y Mantenimiento de Espacio

Este paso explica cómo verificar el espacio real ocupado por Docker, cómo manejar los cachés de construcción y cómo evitar que OneDrive llene tu disco local innecesariamente.

🔍 15.1 Verificar consumo real de Docker

Antes de hacer cualquier limpieza en tu máquina, revisa qué tanto espacio ocupan realmente las imágenes, contenedores y volúmenes de Docker:

docker system df

Esto muestra:

• Images → espacio usado por imágenes descargadas o construidas.
• Containers → contenedores activos o detenidos.
• Local Volumes → volúmenes persistentes.
• Build Cache → caché de construcción de imágenes.

👉 Si todos los valores aparecen en 0B, significa que Docker ya no ocupa espacio en tu disco.

📦 15.2 Imágenes y build cache

• Una imagen final (ej. pretext-curso:latest) es lo que usas al ejecutar un contenedor.
• El build cache son capas intermedias guardadas por Docker para acelerar futuras compilaciones de imágenes.
• Los contenedores no usan el cache, solo la imagen final.

✅ Puedes borrar el cache sin afectar tus contenedores:

docker builder prune -a

Esto elimina todas las capas intermedias y recupera espacio.
⚠️ Única desventaja: la próxima vez que compiles una imagen, Docker tendrá que rehacer todo desde cero (descargas, instalaciones, etc.), lo que será más lento.

📂 15.3 Revisar el archivo de disco de Docker

Docker en Windows con WSL2 guarda todo dentro de un archivo ext4.vhdx, ubicado en:

C:\Users\<TU_USUARIO>\AppData\Local\Docker\wsl\main\ext4.vhdx

Ese archivo puede crecer aunque borres imágenes. Para compactarlo y recuperar espacio físico:

Método universal con diskpart

1. Abre PowerShell como Administrador y escribe:

   diskpart
   

2. Dentro de diskpart, ejecuta:

   select vdisk file="C:\Users\<TU_USUARIO>\AppData\Local\Docker\wsl\main\ext4.vhdx"
   attach vdisk readonly
   compact vdisk
   detach vdisk
   exit
   

3. Reinicia Docker Desktop para aplicar los cambios.

☁️ 15.4 Manejo de OneDrive

Muchas veces Windows muestra que tu disco está lleno cuando realmente el espacio ocupado proviene de OneDrive sincronizado.

Pasos recomendados:

1. Verifica el tamaño local real

   • Haz clic derecho sobre C:\Users\<TU_USUARIO>\OneDrive... → Propiedades.
   • Observa el campo Tamaño en disco (ese es el que ocupa localmente, no el “tamaño total” en la nube).

2. Liberar espacio local sin borrar archivos de la nube

   • Haz clic derecho sobre la carpeta OneDrive o archivos pesados → selecciona “Liberar espacio”.
   • Esto elimina los datos locales y deja solo accesos directos a la nube.

3. Desactivar o mover OneDrive

   • Si no quieres que OneDrive use tu SSD principal:
     • Abre la aplicación de OneDrive.
     • Ve a Configuración > Cuenta > Desvincular esta PC.
     • Luego reconfigura la sincronización en otro disco (ejemplo, un SSD externo).

✅ 15.5 Flujo recomendado

1. Corre siempre primero:

   docker system df
   

   para confirmar si Docker ocupa espacio.

2. Si Docker no ocupa nada → pasa a revisar OneDrive.

3. Si Docker muestra mucho espacio en Build Cache → limpia con:

   docker builder prune -a
   

4. Si el archivo ext4.vhdx sigue muy grande → compacta con diskpart.

5. Finalmente, revisa la configuración de OneDrive para liberar espacio local.

📌 Con este procedimiento tienes control tanto del espacio usado por Docker como por OneDrive, y evitas perder gigas en tu disco principal.

✅ Con estos comandos tienes lo esencial para crear, ejecutar, reanudar, limpiar, respaldar y servir tus proyectos de PreTeXt con Docker en tu flujo de trabajo con MetaLibros.