DEV Community: Raül Martínez i Peris

ROCm

Raül Martínez i Peris — Wed, 31 Dec 2025 14:12:19 +0000

NOTA: Este documento está basado en Ubuntu.

¿Todavía no sabes que es ROCm?

ROCm es la alternativa libre a CUDA. Es cierto que CUDA le lleva ventaja, pero, las cosas empiezan a cambiar, sobre todo debido a la deriva del mercado... Nvidia no puede "cubrir" la demanda mundial y ello a dado una ventana de oportunidad a que AMD pueda convencer.

ROCm son drivers libres para las GPU, aunque es evidente que al estar bajo el paraguas de AMD es sobretodo para AMDGPUs: https://rocm.docs.amd.com/en/latest/index.html

I. Diagnosticar tu AMDGPU

Lo primero es instalar las herramientas de diagnóstico necesarias:

sudo apt update && sudo apt install -y lshw

Y tras ello, ejecutamos el diagnóstico:

sudo lshw -c video 2>/dev/null | grep "configuration"

Para la validación del resultado debes buscar la cadena driver=amdgpu:

configuration: driver=amdgpu latency=0: El sistema gráfico está correctamente anclado al driver nativo.

configuration: driver=llvmpipe ... (O salida vacía / driver=unsigned): el sistema no está usando aceleración hardware.

Instalar/restaurar drivers nativos

A) Eliminar completamente instalaciones propietarias anteriores:

sudo amdgpu-install --uninstall 2>/dev/null
sudo apt purge -y "amdgpu-*" "rocm-*" "hsa-*"

B) Forzar la reinstalación del stack gráfico nativo de Ubuntu:

sudo apt update
sudo apt install --reinstall xserver-xorg-video-amdgpu xserver-xorg-core libgl1-mesa-dri
sudo apt install --reinstall linux-image-generic linux-headers-generic

C) Regenerar imagen de arranque y reiniciar:

sudo update-initramfs -u
sudo reboot

II. Configuración

Vamos a realizar la configuración para una iGPU Radeon, más exactamente configuramos un equipo con Ryzen AI 9 y Radeon 780M/880M.

sudo apt update && sudo apt install -y build-essential git curl cmake

UBUNTU_CODENAME=$(lsb_release -sc)
BASE_URL="https://repo.radeon.com/amdgpu-install/7.1.1/ubuntu/$UBUNTU_CODENAME/"

INSTALLER_FILE=$(curl -s "$BASE_URL" | grep -o 'amdgpu-install_[0-9.-]*_all.deb' | sort -V | tail -n 1)

if [ -z "$INSTALLER_FILE" ]; then
    echo "Error Crítico: No se localizó el paquete instalador en $BASE_URL"
    exit 1
fi

wget -c "$BASE_URL$INSTALLER_FILE"

sudo apt install -y "./$INSTALLER_FILE"

# Desplegando pila ROCm y HIP (User-space).
# El flag --no-dkms evita la recompilación del módulo del kernel, previniendo conflictos gráficos.
sudo amdgpu-install --usecase=rocm,hip --no-dkms -y

sudo usermod -aG render,video $USER

# Inyección de variable de entorno para compatibilidad con RDNA 3.5
if ! grep -q "HSA_OVERRIDE_GFX_VERSION=11.0.0" ~/.bashrc; then
    echo 'export HSA_OVERRIDE_GFX_VERSION=11.0.0' >> ~/.bashrc
fi

III. Comprobaciones y tests

Primero revisemos que tenemos la GPU:

lspci | grep -i amd

Deberías ver tu gráfica en el listado.

Si tienes memoria compartida (shared memory) deberás habilitar el máximo que necesites en tu BIOS (UMA Frame Buffer Size o Integrated Graphics Memory).

Preparar un contenedor para las comprobaciones.

Crea un Dockerfile:

FROM rocm/pytorch:rocm6.1_ubuntu22.04_py3.10_pytorch_2.1.2

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y \
    rocm-smi \
    git \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

ENV HSA_OVERRIDE_GFX_VERSION=11.0.0

WORKDIR /app

COPY test_gpu.py .

CMD ["/bin/bash", "-c", "python3 test_gpu.py; bash"]

... y para facilitar el uso, también creamos un compose.yml:

services:
  rocm-strix:
    build: .
    image: rocm-strix:v1
    container_name: rocm_strix_container
    restart: unless-stopped

    # Fundamental para el acceso al hardware
    devices:
      - "/dev/kfd:/dev/kfd"
      - "/dev/dri:/dev/dri"

    # Permisos de seguridad relajados para acceso a memoria GPU
    security_opt:
      - seccomp:unconfined
    cap_add:
      - SYS_PTRACE

    # Grupos necesarios para acceder a video/render
    group_add:
      - video
      - render

    # Vital para PyTorch y sus DataLoaders (memoria compartida)
    ipc: host

    environment:
      # CRÍTICO: Engaña a la librería para usar kernels de RX 7900 en la APU que estoy testeando
      - HSA_OVERRIDE_GFX_VERSION=11.0.0
      - ROCM_PATH=/opt/rocm
      # Opcional: Define la zona horaria
      - TZ=Europe/Madrid 

    volumes:
      - ./data:/app/data
      # --- Acceso al Hardware ---
      - /sys/class/power_supply:/sys/class/power_supply:ro
      - /sys/class/drm:/sys/class/drm:ro
      - /sys/class/hwmon:/sys/class/hwmon:ro

Y por último un pequeño script, test_gpu.py:

import torch
import time
import psutil
import platform
import os
import subprocess
import json

def format_bytes(size):
    power = 2**10
    n = 0
    power_labels = {0 : 'B', 1: 'KB', 2: 'MB', 3: 'GB', 4: 'TB'}
    while size > power:
        size /= power
        n += 1
    return f"{size:.2f} {power_labels[n]}"

def get_cpu_info():
    try:
        command = "cat /proc/cpuinfo | grep 'model name' | uniq | cut -d : -f 2"
        cpu_name = subprocess.check_output(command, shell=True).decode().strip()
    except:
        cpu_name = platform.processor()

    logical = psutil.cpu_count(logical=True)
    physical = psutil.cpu_count(logical=False)
    freq = psutil.cpu_freq()
    freq_str = f"{freq.max:.0f} Mhz" if freq else "Unknown"
    return cpu_name, physical, logical, freq_str

def get_battery_status():
    if not hasattr(psutil, "sensors_battery"): return "No soportado"
    try:
        battery = psutil.sensors_battery()
        if battery is None: return "No detectada"
        plugged = "CONECTADO" if battery.power_plugged else "BATERÍA"
        return f"{battery.percent}% ({plugged})"
    except: return "Error leyendo batería"

def get_gpu_sensors_rocm():
    data = {}
    try:
        # Intentamos obtener JSON. Si falla, manejamos la excepción.
        raw_json = subprocess.check_output("rocm-smi -a --json", shell=True).decode()
        smi_data = json.loads(raw_json)
        card = list(smi_data.keys())[0]
        gpu_data = smi_data[card]

        # --- LÓGICA DE NOTAS EXPLICATIVAS ---

        # 1. TEMPERATURAS
        edge = gpu_data.get("Temperature (Sensor edge) (C)", "N/A")
        junc = gpu_data.get("Temperature (Sensor junction) (C)", "N/A")
        if junc == "N/A": junc = "N/A (APU: Solo reporta sensor Edge)"
        data['temp'] = f"{edge}°C (Edge) / {junc}"

        # 2. CONSUMO (POWER)
        pwr = gpu_data.get("Average Graphics Package Power (W)", "N/A")
        if pwr == "N/A": pwr = "N/A (APU: Energía compartida CPU/GPU)"
        data['power'] = pwr

        # 3. RELOJES (CLOCKS)
        sclk = gpu_data.get("SCLK", "N/A")
        mclk = gpu_data.get("MCLK", "N/A")
        if sclk == "N/A" or mclk == "N/A":
            # Si Docker bloquea uno, bloquea los dos. Ponemos un mensaje global.
            data['clocks'] = "N/A / N/A (Docker: Ambos sensores (SCLK/MCLK) bloqueados por aislamiento)"
        else:
            data['clocks'] = f"{sclk} / {mclk}"

        # 4. VENTILADOR
        fan = gpu_data.get("Fan Speed (%)", "N/A")
        if fan == "N/A": fan = "N/A (Laptop: Controlado por BIOS/EC)"
        data['fan'] = fan

        # 5. CARGA Y MEMORIA
        data['usage'] = gpu_data.get("GPU use (%)", "N/A")
        data['vram_used'] = gpu_data.get("VRAM Total Used Memory (B)", 0)
        data['gtt_used'] = gpu_data.get("GTT Total Used Memory (B)", 0)

    except Exception as e:
        data['error'] = f"Error interpretando sensores: {str(e)}"
        # Valores por defecto seguros para que no rompa el print
        data['temp'] = "Error"
        data['power'] = "Error"
        data['clocks'] = "Error"
        data['fan'] = "Error"
        data['usage'] = "?"
        data['vram_used'] = 0
        data['gtt_used'] = 0

    return data

def benchmark_latency(iters=1000):
    start = torch.cuda.Event(enable_timing=True)
    end = torch.cuda.Event(enable_timing=True)
    for _ in range(100): torch.cuda.synchronize() # Warmup
    start.record()
    for _ in range(iters): torch.cuda.synchronize()
    end.record()
    torch.cuda.synchronize()
    return (start.elapsed_time(end) / iters) * 1000

def benchmark_bandwidth(size_mb=512):
    elements = size_mb * 1024 * 1024 // 4 
    t_cpu = torch.randn(elements, dtype=torch.float32)
    torch.cuda.synchronize()

    # H2D
    start = time.time()
    t_gpu = t_cpu.to('cuda')
    torch.cuda.synchronize()
    h2d = (size_mb / 1024) / (time.time() - start)

    # D2H
    start = time.time()
    _ = t_gpu.to('cpu')
    torch.cuda.synchronize()
    d2h = (size_mb / 1024) / (time.time() - start)
    return h2d, d2h

def benchmark_compute(n, dtype):
    a = torch.randn(n, n, device="cuda", dtype=dtype)
    b = torch.randn(n, n, device="cuda", dtype=dtype)
    torch.mm(a, b)
    torch.cuda.synchronize()
    start = time.time()
    torch.mm(a, b)
    torch.cuda.synchronize()
    ops = 2 * (n ** 3)
    return (ops / (time.time() - start)) / 1e12

# ================= REPORT =================
print("\n" + "="*60)
print("          ROCm ULTIMATE DIAGNOSTIC TOOL     ")
print("="*60)

# [1] HOST
cpu, _, _, _ = get_cpu_info()
vm = psutil.virtual_memory()
print(f"\n[1] HOST & ENERGÍA")
print(f"CPU:             {cpu}")
print(f"RAM Sistema:     {format_bytes(vm.available)} libres / {format_bytes(vm.total)} Total")
print(f"Estado Energía:  {get_battery_status()}")

# [2] GPU
print(f"\n[2] SENSORES GPU (ROCm SMI)")
if torch.cuda.is_available():
    sensors = get_gpu_sensors_rocm()
    d = 0
    props = torch.cuda.get_device_properties(d)
    print(f"Dispositivo:     {torch.cuda.get_device_name(d)}")
    print(f"VRAM Total:      {format_bytes(props.total_memory)}")
    print(f"-"*40)
    print(f"Temp:            {sensors.get('temp', '?')}")
    print(f"Consumo:         {sensors.get('power', '?')}")
    print(f"Relojes:         {sensors.get('clocks', '?')}")
    print(f"Ventilador:      {sensors.get('fan', '?')}")
    print(f"-"*40)
    print(f"Carga GPU:       {sensors.get('usage', '?')}%")
    print(f"Memoria Usada:   VRAM: {format_bytes(float(sensors.get('vram_used', 0)))} | GTT: {format_bytes(float(sensors.get('gtt_used', 0)))}")
else:
    print("FATAL: GPU NO DETECTADA")

# [3] BENCHMARKS
print(f"\n[3] PRUEBAS DE ESTRÉS & RENDIMIENTO")
print(f"Latencia Kernel: {benchmark_latency():.2f} µs")
try:
    h2d, d2h = benchmark_bandwidth(512)
    print(f"Ancho Banda:     Escritura: {h2d:.2f} GB/s | Lectura: {d2h:.2f} GB/s")
except: print("Error memoria")

print("\n--- Potencia de Cómputo ---")
for size in [4096, 8192]:
    tf32 = benchmark_compute(size, torch.float32)
    print(f"Matriz {size}x{size}: FP32: {tf32:.2f} TFLOPS", end="")
    try:
        tf16 = benchmark_compute(size, torch.float16)
        print(f" | FP16: {tf16:.2f} TFLOPS (Boost: {tf16/tf32:.2f}x)")
    except: print("")

print("\n" + "-"*60 + "\n")

Y ahora, para probarlo:

docker compose build
docker compose up

Si algo falla y necesitas recrear el contenedor, debes eliminarlo previamente con:

docker rm -f rocm_strix_container

Por último, puedes ver el estado de la GPU con:

rocm-smi

y del sistema con:

htop

Windows: container Windows + container Linux (& VI)

Raül Martínez i Peris — Thu, 09 Oct 2025 12:50:25 +0000

Índice

Sección primera (básico):
- Docker en Windows. Apartado I: Instalar WSL2 (y Docker).
- Docker en Windows. Apartado II: Instalar Docker en Windows 11.
Sección segunda (avanzado):
- Docker en Windows. Apartado III: Confianza entre entornos.
- Docker en Windows. Apartado IV: Configurar conexión entre Docker Windows y Docker WSL.
- Docker en Windows. Apartado V: Instalar Portainer en el entorno WSL.
- Docker en Windows. Apartado VI: Apuntes.

Apartado VI. Apuntes

En este momento ya tenemos los dos contextos configurados. Veamos como consultar los context desde cada entorno.

Desde Windows

Para ver el listado de contextos:

docker context ls

Para utilizar docker con Windows:

docker context use windows

Para utilizar docker con Ubuntu:

docker context use wsl

Desde WSL

Para ver el listado de contextos:

docker context ls

Para utilizar docker con Windows:

docker context use windows-from-wsl

Para utilizar docker con Ubuntu:

docker context use default

Notas finales

Ten en cuenta que necesitas la virtualización de WSL para poder ejecutar contenedores en el entorno Linux; por ello, hemos activado que se levante automáticamente. Aunque si lo prefieres, puedes quitar el archivo de inicio automático y simplemente levantarlo con “wsl -d Ubuntu” antes de lanzar cualquier docker del entorno Linux.

Errores conocidos

Después de una actualización del sistema o por cambios en directivas, WSL no funciona correctamente: revisa si la ejecución de scripts se ha deshabilitado. Ejecuta el comando:

Get-ExecutionPolicy -List

Si no tienes permisos para ejecutar scripts, vuelve a definirlos:

Set-ExecutionPolicy Unrestricted -Scope CurrentUser

Windows: container Windows + container Linux (V)

Raül Martínez i Peris — Thu, 09 Oct 2025 12:49:50 +0000

Índice

Sección primera (básico):
- Docker en Windows. Apartado I: Instalar WSL2 (y Docker).
- Docker en Windows. Apartado II: Instalar Docker en Windows 11.
Sección segunda (avanzado):
- Docker en Windows. Apartado III: Confianza entre entornos.
- Docker en Windows. Apartado IV: Configurar conexión entre Docker Windows y Docker WSL.
- Docker en Windows. Apartado V: Instalar Portainer en el entorno WSL.
- Docker en Windows. Apartado VI: Apuntes.

Este apartado lo añadimos como ejemplo de instalación de un contenedor Linux que puede "manejar" también los contenedores Windows.

Apartado V. Instalar Portainer en el entorno WSL

Si no estabas dentro de la consola de Linux, entra en la distro con:

wsl -d ubuntu

confirma que estás en el contexto ‘default’; y sin más dilación, lancemos la creación del contenedor:

docker run -d -p 9000:9000 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ce

Una vez terminado, accedemos a la url “localhost:9000”: creamos el usuario admin, y ya está.

Ahora toca configurar los dos “contextos” o “entornos”, para ello, pulsa sobre “Add Environments” y lanzamos el “Wizard” de “Docker Standalone”:

Para el Docker de WSL (Ubuntu) le indicaremos que coja el socket por defecto, le indicamos un nombre, le damos a “Connect” y después a “Close”.

Volvemos al menú para añadir otro entorno, seleccionamos Docker Standalone y “API”:

Le indicamos un nombre al entorno y le indicamos la URL. En nuestro caso la URL corresponde con el hostname wsl2docker.local que hemos preparado y el puerto 2375. Recuerda que ya deberías haber configurado el archivo “hosts” de Windows. Además, tendrás que indicar los certificados: ca.pem, client-cert.pem y client-key.pem que preparamos y que tienes en tu carpeta C:\ProgramData\docker\certs.

Una vez completado pulsa el botón “Connect” y “Close”.

Ahora ya podemos ir a “Home” y veremos los dos entornos. Tenemos a la vista tanto los contenedores del context/environment de Windows como de los de WSL (Linux).

Enlaces

Portainer: https://docs.portainer.io/start/install-ce

Siguiente artículo:

Docker en Windows. Apartado VI: Apuntes.

Windows: container Windows + container Linux (IV)

Raül Martínez i Peris — Thu, 09 Oct 2025 12:49:17 +0000

Índice

Sección primera (básico):
- Docker en Windows. Apartado I: Instalar WSL2 (y Docker).
- Docker en Windows. Apartado II: Instalar Docker en Windows 11.
Sección segunda (avanzado):
- Docker en Windows. Apartado III: Confianza entre entornos.
- Docker en Windows. Apartado IV: Configurar conexión entre Docker Windows y Docker WSL.
- Docker en Windows. Apartado V: Instalar Portainer en el entorno WSL.
- Docker en Windows. Apartado VI: Apuntes.

Apartado IV. Configurar conexión entre Docker Windows y Docker WSL

Para empezar, abre una consola Powershell.

Crear reglas para el Firewall

Como sabes, los servicios en contenedores necesitan salir por un puerto para conversar con otros servicios o aplicaciones. Por ello, es necesario que pongas una regla en el cortafuegos para permitirlo.

Vamos a crear una regla de ejemplo para permitir el acceso al puerto 8080:

New-NetFirewallRule -DisplayName "Web TCP 8080" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow

Adicionalmente, revisa el puerto 443 (aunque suele estar abierto) y ábrelo si es necesario:

New-NetFirewallRule -DisplayName "HTTPS" -Direction Inbound -Protocol TCP -LocalPort 443 -Action Allow

Cada vez que crees un contenedor deberás verificar que el puerto esté abierto.

Crear reglas en el Firewall para Docker

Vamos a crear las reglas necesarias para la escucha entre los Docker de ambos entornos, para ello abriremos el puerto 2375.

Para permitir el acceso al puerto 2375, crea la regla:

New-NetFirewallRule -DisplayName "Docker TCP 2375" -Direction Inbound -Protocol TCP -Action Allow -LocalPort 2375

Reiniciar el servicio Docker

Para que los cambios surtan efecto deberemos reiniciar el servicio de Docker:

net stop Docker
net start Docker

Comprueba que el servicio Docker está funcionando:

Get-Service docker

Configurar el demonio de Docker WSL

Entra en el entorno de Ubuntu:

wsl -d ubuntu

Comprueba que tienes los archivos wsl-server-cert.pem, wsl-server-key.pem y ca.pem:

ls /mnt/c/ProgramData/docker/certs/

Creamos el directorio para Docker (si no lo estuviera) y creamos el archivo daemon.json:

sudo mkdir -p /etc/docker
sudo nano /etc/docker/daemon.json

con el contenido:

{
"hosts": [
  "unix:///var/run/docker.sock",
  "tcp://0.0.0.0:2376"
],
"tlsverify": true,
"tlscacert": "/mnt/c/ProgramData/certs/ca.pem",
"tlscert": "/mnt/c/ProgramData/docker/certs/wsl-server-cert.pem",
"tlskey": "/mnt/c/ProgramData/docker/certs/wsl-server-key.pem"
}

Ahora vamos a crear el archivo override de la configuración:

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo nano /etc/systemd/system/docker.service.d/override.conf

con el contenido:

[Service]
ExecStart=
ExecStart=/usr/bin/dockerd

Y reiniciamos el servicio:

sudo systemctl daemon-reload
sudo service docker restart

El siguiente paso es con Powershell, por lo que debemos salir de Ubuntu:

exit

Y hacerle un shutdown:

wsl --shutdown

Configurar en Windows la conexión al host de Linux

En la consola de Powershell, crea el nuevo contexto para WSL:

$userProfile = $env:USERPROFILE
$dockerDir = Join-Path $userProfile ".docker"
docker context create wsl --docker "host=tcp://localhost:2376,ca=$userProfile\.docker\ca.pem,cert=$userProfile\.docker\cert.pem,key=$userProfile\.docker\key.pem"

Aunque es el contexto de WSL, lo estamos configurando en Windows por lo que las rutas para los certificados que utilizamos son los de Windows, no siendo necesario volver a copiarlos.

Añadir las reglas al Firewall

Para permitir el acceso al puerto 2376, crea la regla:

New-NetFirewallRule -DisplayName "Docker TCP 2376" -Direction Inbound -Protocol TCP -Action Allow -LocalPort 2376

Configuración del Docker en WSL con TLS

Copiar las claves TLS a la carpeta de usuario

Ahora vamos a configurar en WSL la conexión al host docker de Windows.

Volvemos a la consola de WSL:

wsl -d ubuntu

Primero copiamos los certificados a la carpeta docker del usuario:

cp /mnt/c/ProgramData/certs/ca.pem ~/.docker/ca.pem
cp /mnt/c/ProgramData/docker/certs/client-cert.pem ~/.docker/cert.pem
cp /mnt/c/ProgramData/docker/certs/client-key.pem ~/.docker/key.pem

Y les ponemos los permisos adecuados:

cd ~/.docker/
chmod -v 0400 key.pem
chmod -v 0444 cert.pem ca.pem

Crear contextos dentro del entorno WSL

Preparar el hostname de conexión

Lo primero es automatizar el nombre hostname en cada inicio de sesión. Para ello vamos a editar el archivo de inicio de sesión:

nano ~/.bashrc

y le añadimos al final del todo el siguiente código:

WINDOWS_DOCKER_HOSTNAME="wsl2docker.local"
WINDOWS_HOST_IP=$(ip route show | grep -i default | awk '{ print $3 }')
sudo sed -i "/${WINDOWS_DOCKER_HOSTNAME}/d" /etc/hosts
echo "${WINDOWS_HOST_IP} ${WINDOWS_DOCKER_HOSTNAME}" | sudo tee -a /etc/hosts
sudo systemctl restart systemd-resolved

En Windows deberíamos controlar que el archivo C:\Windows\System32\drivers\etc\hosts está correctamente configurado, sin embargo, crear un script Powershell que se lance automáticamente en el inicio de Windows para comprobar dicha línea “se sale” de las necesidades que tenemos.

Pero, sí que necesitamos saber si la IP nos ha cambiado, para ello, añadiremos al final del archivo, a continuación de donde acabas de pegar lo anterior, en el archivo ~/.bashrc, una pequeña comprobación:

WINDOWS_HOSTS_PATH="/mnt/c/Windows/System32/drivers/etc/hosts"
HOSTS_LINE=$(grep -i "$WINDOWS_DOCKER_HOSTNAME" "$WINDOWS_HOSTS_PATH" | grep -v "^#")
if [[ "$HOSTS_LINE" == *"$WINDOWS_HOST_IP"* ]]; then
  echo -e "\nLa IP y el Hostname para la conexión entre WSL y Windows están correctamente configuradas en ambos entornos.\n”
else
  echo -e "\nEl archivo de configuración de Windows no está correctamente configurado,"
  echo -e "por favor, abre el archivo '$WINDOWS_HOSTS_PATH' y revisa la siguiente línea:"
  echo -e "$WINDOWS_HOST_IP  $WINDOWS_DOCKER_HOSTNAME"
fi

Esta comprobación nos avisará cuando levantemos WSL2 si coinciden las configuraciones de Windows y WSL2. Si no coinciden nos dirá la ruta del archivo y el contenido que debemos poner.

Crear el contexto de conexión a Windows

Ahora creamos el contexto para ver el Docker de Windows desde WSL:

WINDOWS_DOCKER_HOSTNAME="wsl2docker.local"
docker context create windows-from-wsl --docker "host=tcp://${WINDOWS_DOCKER_HOSTNAME}:2375,ca=${HOME}/.docker/ca.pem,cert=${HOME}/.docker/cert.pem,key=${HOME}/.docker/key.pem"

Para simplificar la comprensión de esta creación de contexto hemos creado una variable llamada hostname para que quede más claro... evidentemente esto no es necesario, puedes escribirlo directamente.

Con este contexto creado, vamos a comprobarlo:

docker context use windows-from-wsl
docker ps

Deberías de haber obtenido como resultado el listado del docker de Windows.

Una vez comprobado el Docker de Windows, puedes volver al contexto predeterminado de WSL (que generalmente apunta al socket unix:///var/run/docker.sock) ejecutando:

docker context use default

Salimos de la consola WSL para continuar en Powershell:

exit

Efectos secundarios

Al introducir en el .bashrc la creación del `hostname+ , tenemos como “inconveniente” que a partir de ahora cada vez que entremos en el entorno WSL nos pedirá la contraseña, ya que hemos incluido una línea de código con “sudo”, lo cual obliga a ejecutarse con los permisos de root.

¿Porqué añadimos la IP que nos entrega ip route show?

Si miras la configuración de redes de tu equipo, verás que tienes una red virtual que se llama “WSL (Hyper-V firewall)”, donde está configurada la IP de nuestro host con acceso a través del firewall. Si desde WSL compruebas con telnet verás que nos permite la conexión.

Finalizar la instalación

Activar WSL en el inicio de sesión.

El único inconveniente que tiene utilizar Docker con WSL es que necesitas tener WSL funcionando.
Por ello, lo mejor es levantar la distro al inicio de sesión y dejar la ventana minimizada.

Para añadir el arranque de WSL al inicio, pulsa Win+R y escribe shell:startup, y presiona Enter.

Ahora, en la ventana que te ha abierto, con el ratón, crea un nuevo acceso directo y escribe:
wsl -d Ubuntu

Para finalizar pulsa siguiente y ponle nombre al acceso directo, por ejemplo, "wsl-Ubuntu".

Enlaces

Siguiente artículo:

Docker en Windows. Apartado V: Instalar Portainer en el entorno WSL2.

Windows: container Windows + container Linux (III)

Raül Martínez i Peris — Thu, 09 Oct 2025 12:48:38 +0000

Índice

Sección primera (básico):
- Docker en Windows. Apartado I: Instalar WSL2 (y Docker).
- Docker en Windows. Apartado II: Instalar Docker en Windows 11.
Sección segunda (avanzado):
- Docker en Windows. Apartado III: Confianza entre entornos.
- Docker en Windows. Apartado IV: Configurar conexión entre Docker Windows y Docker WSL.
- Docker en Windows. Apartado V: Instalar Portainer en el entorno WSL.
- Docker en Windows. Apartado VI: Apuntes.

Con este artículo empezamos la sección avanzada. Además, este apartado lo dividiremos en dos partes: la primera para la creación un certificado CA; y, la segunda para la creación de los certificados TLS que necesitaremos.

Apartado III. Confianza entre entornos

¿Para qué necesitamos tener un certificado de una CA?

Vamos a conectar el docker de Windows con el docker de WSL, para lo cual al tener que realizar la conexión por dominio/IP necesitamos que ambas virtualizaciones confíen entre ellas... lo que no s obliga a tener certificados firmados por una CA. Aquí tenemos dos opciones: pagamos o no pagamos. Para esta sección de Docker nos interesa el aprendizaje de crear la CA y utilizarla.

Primera parte: Crear una CA (Autoridad Certificadora) para usos internos

Descargar e instalar OpenSSL

Descarga el instalador de OpenSSL Win32OpenSSL de slproweb. Este instalador es un empaquetado por un tercero, si necesitas el código de OpenSSL sin empaquetar tienes los enlaces al final del artículo. Sea cual sea la opción que tomes, debes instalarlo antes de continuar.

Configurar OpenSSL

Abre una consola Powershell.

Lo primero que haremos es añadir la ruta del ejecutable al path:

[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;C:\Program Files\OpenSSL-Win64\bin", [EnvironmentVariableTarget]::Machine)

Asegúrate de haber realizado la instalación en la ruta indicada, o, en caso de que difiera actualiza los datos de la variable de entorno.

Una vez hecho esto debemos reiniciar la consola para que surta efecto.

Ubicación sugerida para los certificados

Normalmente la instalación de Docker crea todas las carpetas necesarias, pero, si no existiera lo correcto es crear la siguiente carpeta C:\ProgramData\certs:

New-Item -ItemType Directory -Force -Path "C:\ProgramData\certs"

Generar los certificados utilizando OpenSSL

Antes de continuar: Recuerda que debes poner especial cuidado en la salvaguarda de las contraseñas, ficheros llave y certificados.

Generar la Llave y el Certificado de la CA (Autoridad Certificadora)

Para que un certificado actúe como CA, debe tener la extensión Basic Constraints con CA:TRUE.

Nos situamos en el directorio:

cd "C:\ProgramData\certs"

Crea un archivo llamado ca.cnf con el siguiente contenido:

[ req ]
distinguished_name = req_distinguished_name
x509_extensions = v3_ca
prompt = no
[ req_distinguished_name ]
C = ES
ST = Comunitat Valenciana
L = Valencia
O = EMPRESA
OU = UNIDAD EMPRESARIAL
CN = Mi CA para Docker
[ v3_ca ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, CA:TRUE
keyUsage = critical, digitalSignature, cRLSign, keyCertSign

Ajusta los campos C (Country), ST (State or Province), L (Locality), O (Organization), OU (Organizational Unit) y CN (Common Name) según tus necesidades.

Es importante utilizar un CN que nos permita tener una buena descripción de su cometido, por ejemplo un CN conveniente para este caso sería ca-$($env:COMPUTERNAME)-$($env:USERNAME). Al final del artículo hemos añadido información relevante para su correcta definición.

Genera el certificado llave:

openssl genrsa -aes256 -out ca-key.pem 4096

Te pedirá una contraseña para la clave de la CA. Esta contraseña es necesaria para firmar otros certificados. Como es habitual, guárdatela en tu Keepass o similar.

Genera el certificado (te pedirá la contraseña que has introducido en la llave):

openssl req -new -x509 -days 3650 -key ca-key.pem -sha256 -out ca.pem -config ca.cnf

Ahora para confirmar que es correcto, lanza el siguiente comando:

openssl x509 -in ca.pem -text -noout | Select-String "CA"

En el resultado tendrás que ver que basicConstraints está como critical y con CA:TRUE.

Configurar los permisos de los archivos para WSL

Para ello entramos en una terminal Powershell en modo "Administrador" e introducimos:

wsl -d ubuntu

Ahora nos situamos en el directorio certs:

cd /mnt/c/ProgramData/certs

Ahora limpiamos los archivos sobrantes:

rm *.csr *.cnf *.srl

Por último, vamos a cambiar los permisos:

chmod -v 0400 ca-key.pem
chmod -v 0444 ca.pem

¿Porqué hemos cambiado los permisos desde la terminal de Ubuntu?

Por dos razones:

Es más simple que con Powershell.
Nos aseguramos que tenemos acceso a los archivos en el disco C: de Windows desde el entorno WSL.

Evidentemente, puedes optar por cambiar los permisos desde Powershell.

Segunda parte: Configuración de la comunicación interna de los entornos

Debes tener un certificado CA antes de continuar.

Generar certificados TLS

Antes de configurar Docker tanto en Windows como WSL necesitas generar los certificados TLS. Estos certificados asegurarán la comunicación entre el cliente Docker y el daemon Docker. Necesitarás una Autoridad Certificadora (CA), el cual ya lo habrás preparado anteriormente.

Normalmente la instalación de Docker crea todas las carpetas necesarias, pero, si no existiera lo correcto es crear la carpeta C:\ProgramData\docker\certs para los certificados:

New-Item -ItemType Directory -Force -Path "C:\ProgramData\docker\certs"

Nos situamos en el directorio:

cd "C:\ProgramData\docker\certs"

Generar los certificados utilizando OpenSSL

Es necesario que tengas un certificado de una CA para realizar los siguientes pasos como se indicó en el anterior apartado.

Si ha seguido las indicaciones del documento, tendrás en la carpeta C:\ProgramData\certs el certificado CA ya creado. Créate el enlace en una variable para acceder rápidamente a ellos:

$caPem = "C:\ProgramData\certs\ca.pem"
$caKeyPem = "C:\ProgramData\certs\ca-key.pem"

Generar Clave y Certificado del Servidor para Docker en Windows

En este paso tendremos en cuenta que debemos configurarlo para que escuche a través de localhost.

openssl genrsa -out win-server-key.pem 4096
openssl req -subj "/CN=localhost" -sha256 -new -key win-server-key.pem -out win-server.csr

Consultamos el nombre de nuestro equipo lanzando el comando:

hostname

Ahora creamos el archivo extfile-win.cnf con el siguiente contenido utilizando el resultado de hostname (sustituyendo xNAMEx):

subjectAltName = DNS:localhost,IP:127.0.0.1,IP:::1,DNS:xNAMEx,DNS:wsl2docker.local
extendedKeyUsage = serverAuth

Como es lógico, cambiamos el DNS indicado (xNAMEx) por el nombre de tu máquina, y, además introducimos un nuevo DNS que será utilizado para “conectar” el entorno Windows y WSL sin necesidad de depender de una IP (esto nos permite que el certificado continúe siendo válido incluso si nos cambia la IP).

Ahora firma la CSR del servidor de Windows con tu CA:

$caPem = "C:\ProgramData\certs\ca.pem"
$caKeyPem = "C:\ProgramData\certs\ca-key.pem"
Copy-Item -Path $caPem "C:\ProgramData\docker\certs\ca.pem"
openssl x509 -req -days 3650 -sha256 -in win-server.csr -CA ca.pem -CAkey $caKeyPem -CAcreateserial -out win-server-cert.pem -extfile extfile-win.cnf

(te pedirá la contraseña de tu llave).

Generar Clave y Certificado del Servidor para Docker en WSL2

Seguimos los mismos pasos para el de WSL2:

openssl genrsa -out wsl-server-key.pem 4096
openssl req -subj "/CN=localhost" -sha256 -new -key wsl-server-key.pem -out wsl-server.csr

Creamos el archivo configuración de extensiones extfile-wsl.cnf:

subjectAltName = DNS:localhost,IP:127.0.0.1,IP:::1,DNS:wsl2docker.local
extendedKeyUsage = serverAuth

Firmamos el CSR del servidor de WSL2 con el CA:

openssl x509 -req -days 3650 -sha256 -in wsl-server.csr -CA ca.pem -CAkey $caKeyPem -CAcreateserial -out wsl-server-cert.pem -extfile extfile-wsl.cnf

(te pedirá la contraseña de tu llave).

Generar Clave y Certificado del Cliente (para docker CLI)

Los mismos pasos:

openssl genrsa -out client-key.pem 4096
openssl req -subj "/CN=client" -new -key client-key.pem -out client.csr

Creamos el archivo de configuración de extensiones extfile-client.cnf:

extendedKeyUsage = clientAuth

Y firmamos el CSR:

openssl x509 -req -days 3650 -sha256 -in client.csr -CA ca.pem -CAkey $caKeyPem -CAcreateserial -out client-cert.pem -extfile extfile-client.cnf

(te pedirá la contraseña de tu llave).

Configurar los permisos de los archivos

Aprovechamos que tenemos instalado WSL y terminamos de configurar los archivos desde la terminal de Ubuntu. Para ello entramos en una terminal powershell en modo "Administrador" e introducimos:

wsl -d ubuntu

Ahora nos situamos en el directorio apropiado (certs de Docker):

cd /mnt/c/ProgramData/docker/certs

Limpiamos los archivos sobrantes:

rm *.csr *.cnf *.srl

Cambiamos los permisos:

chmod -v 0400 client-key.pem
chmod -v 0444 client-cert.pem

Salimos de la shell de Ubuntu:

exit

Y cerramos la consola con permisos Administrador que hemos abierto.

Configurar Docker en Windows para utilizar los certificados TLS

Recordemos lo que tenemos. Los archivos resultantes se dividen en:

Clave CA o certificadora: archivos ca.pem y ca-key.pem. Estos archivos debes guardarlos offline en un lugar seguro.
Claves para el cliente docker: ca.pem, client-cert.pem y client-key.pem.

En cuanto a las claves para el cliente, terminarán siendo colocadas en otros directorios (pero esto lo veremos después): en WSL, en la carpeta ~/.docker/ y en windows en la carpeta %USERPROFILE%\.docker\. Vamos a ello.

Copiar las claves TLS a la carpeta de usuario

Primero, nos aseguramos de que los certificados de cliente (ca.pem, client-cert.pem, client-key.pem) están en %USERPROFILE%\.docker\ con el nombre adecuado. En la terminal de Powershell:

$userProfile = $env:USERPROFILE
$dockerDir = Join-Path $userProfile ".docker"
If (-not (Test-Path $dockerDir)) { New-Item -Path $dockerDir -ItemType Directory }
Copy-Item "$caPem" -Destination (Join-Path $dockerDir "ca.pem")
Copy-Item "C:\ProgramData\Docker\certs\client-cert.pem" -Destination (Join-Path $dockerDir "cert.pem")
Copy-Item "C:\ProgramData\Docker\certs\client-key.pem" -Destination (Join-Path $dockerDir "key.pem")

Configuración del demonio

Utiliza Notepad++ (o el editor que prefieras) para crear el archivo:
C:\ProgramData\docker\config\daemon.json
con el contenido:

{
"hosts": ["tcp://0.0.0.0:2375", "npipe://"],
"tlsverify": true,
"tlscacert": "C:\\ProgramData\\docker\\certs\\ca.pem",
"tlscert": "C:\\ProgramData\\docker\\certs\\win-server-cert.pem",
"tlskey": "C:\\ProgramData\\docker\\certs\\win-server-key.pem"
}

Configurar un contexto para Windows

Necesitaremos utilizar “contextos” de Docker, para entre otros, conectar sin problemas desde VSCode a Docker, o desde el otro entorno.

Pero, primero verificamos que no tenemos el contexto ya creado con anterioridad:

docker context ls

(Nota: Si lo tienes deberías borrarlo, utiliza el comando docker context rm NombreContexto -f.)

Ahora, crea el contexto con el nombre “windows” para Windows:

docker context create windows --docker "host=tcp://localhost:2375,ca=$userProfile\.docker\ca.pem,cert=$userProfile\.docker\cert.pem,key=$userProfile\.docker\key.pem"

Verifica que se ha creado correctamente:

docker context inspect windows

Y actívalo:

docker context use windows

Apuntes

Para crear una CA hay que tener en cuenta las siguientes normativas o estándares:

Formato y estructura. X.509 implementado vía RFC 5280: https://datatracker.ietf.org/doc/html/rfc5280
Certificados web (SSL/TLS): https://cabforum.org/working-groups/server/baseline-requirements/about/
Validez legal, reglamento UE eIDAS y leyes nacionales BOE
Funcionamiento interno, Declaración de Prácticas de Certificación de cada CA específica, por lo que debe buscar la DPC que puede afectarle para documentarse. Como ejemplo enlazamos la normativa de la FNMT (emisión de certificados oficiales en España) en su web de la Sede Electrónica de la Real Casa de la Moneda; y, al BOE con la disposición para la expedición de DNI y certificados digitales

Enlaces

OpenSSL
GitHub de OpenSSL
Empaquetado para Windows por Shining Light Productions

Siguiente artículo:

Docker en Windows. Apartado IV: Configurar conexión entre Docker Windows y Docker WSL.

Windows: container Windows + container Linux (II)

Raül Martínez i Peris — Thu, 09 Oct 2025 12:48:05 +0000

Índice

Sección primera (básico):
- Docker en Windows. Apartado I: Instalar WSL2 (y Docker).
- Docker en Windows. Apartado II: Instalar Docker en Windows 11.
Sección segunda (avanzado):
- Docker en Windows. Apartado III: Confianza entre entornos.
- Docker en Windows. Apartado IV: Configurar conexión entre Docker Windows y Docker WSL.
- Docker en Windows. Apartado V: Instalar Portainer en el entorno WSL.
- Docker en Windows. Apartado VI: Apuntes.

Apartado II. Instalar Docker en Windows 11

En este documento mostramos como instalar Docker con la licencia gratuita.

Nota: durante todo el proceso de instalación vas a necesitar ejecutar los comandos de Powershell en una consola con permisos de Administrador.

Por defecto Windows tiene la ejecución de scripts deshabilitada (solo permite los ‘RemoteSigned’).

La primera vez, para habilitar la ejecución de scripts hay que lanzar el comando:

Set-ExecutionPolicy Unrestricted -Scope CurrentUser

Activar contenedores Windows

Instalamos las capacidades de contenedores para Windows (te pedirá reiniciar):

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All
Enable-WindowsOptionalFeature -Online -FeatureName Containers -All

Reinicia el ordenador (si no lo has hecho tras instalar las features) para que se apliquen las configuraciones.

Instalación de Docker en Windows

Para una instalación simple y rápida Docker en Windows tenemos un script automatizado, tienes el enlace al final del documento. Pero, mejor realicemos la instalación manual...

Vamos a ello, descarga el binario de Docker CLI desde la línea de comandos:

Set-Location $env:USERPROFILE\Downloads
Invoke-WebRequest -Uri "https://download.docker.com/win/static/stable/x86_64/docker-27.4.1.zip" -OutFile "docker.zip"

Extrae el archivo:

Expand-Archive -Path "docker.zip" -DestinationPath “C:\ProgramData”

Agrega la CLI al path de Windows:

$env:Path += ";C:\ProgramData\docker"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [EnvironmentVariableTarget]::Machine)

Creación del servicio para Windows

Crea el servicio para Windows:

sc.exe create Docker binPath= "C:\ProgramData\docker\dockerd.exe --run-service" start= auto

e inícialo:

net start Docker

Instalar ‘docker compose’

Comprueba si está instalado:

docker compose version

En caso negativo, vamos a instalar el plug-in para ‘docker compose’...

Primero crea la carpeta para los plug-ins (si no está creada):

mkdir C:\ProgramData\docker\cli-plugins -Force

Ahora descarga el plug-in directamente en la carpeta:

Invoke-WebRequest -Uri "https://github.com/docker/compose/releases/latest/download/docker-compose-windows-x86_64.exe" -OutFile "C:\ProgramData\docker\cli-plugins\docker-compose.exe"

Finalmente, comprueba que funciona:

docker compose version

Enlaces

GitHub de Microsoft: instalador de Docker

Siguiente artículo:

Docker en Windows. Apartado III: Confianza entre entornos.

Windows: container Windows + container Linux (I)

Raül Martínez i Peris — Thu, 09 Oct 2025 12:47:46 +0000

Índice

Sección primera (básico):
- Docker en Windows. Apartado I: Instalar WSL2 (y Docker).
- Docker en Windows. Apartado II: Instalar Docker en Windows 11.
Sección segunda (avanzado):
- Docker en Windows. Apartado III: Confianza entre entornos.
- Docker en Windows. Apartado IV: Configurar conexión entre Docker Windows y Docker WSL.
- Docker en Windows. Apartado V: Instalar Portainer en el entorno WSL.
- Docker en Windows. Apartado VI: Apuntes.

Si has empezado a leer es porque te has encontrado con la necesidad de poner en funcionamiento la virtualización para contenedores Windows y te has tropezado con que no podías utilizar contenedores Linux. Además, si te instalas la virtualización para contenedores Linux te pasará que no puedes utilizar la virtualización Hyper-V de Windows.

En esta sección crearemos un entorno en el cual podamos lanzar contenedores Windows y Linux.

Hemos dividido esta sección en dos:

En la primera (básica), hacemos una instalación de WSL2 y Docker (en Windows y WSL2).
En la segunda (avanzada), el resto de los apartados, en los cuales realizamos la configuración de ambos entornos Docker y los conectamos, lo cual incluye poner en funcionamiento una CA para usos internos.

Apartado I. Instalar WSL2 (y Docker)

Se llama WSL al Subsistema Linux en Windows, una virtualización capaz de tener funcionando un sistema Linux dentro de un sistema Windows.

Pon atención a la consola que estás utilizando, ya que te encontrarás con tres casos:

Consola CMD.
Consola Powershell.
Consola Linux.

Por defecto utilizaremos la consola Powershell.

Comprobar instalación de WSL2

Primero intentaremos actualizar WSL a la versión 2. Inicia una terminal Powershell y ejecuta:

wsl --update

Si recibes un error porque no tienes habilitado el subsistema, pasa al siguiente apartado, si se ha actualizado, verifica las distribuciones instaladas:

wsl --list --verbose

Si ves que la distribución de Ubuntu está en estado Stopped, puedes ponerla en ejecución con:

wsl -d Ubuntu

Vuelve al entorno Powershell, para ello debes salir de la terminal de Ubuntu, ejecuta:

exit

Instalar WSL2 y Ubuntu en el caso de que no esté instalado

Si no está instalado WSL, debes habilitar la característica WSL, para ello ejecuta en la consola PowerShell:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Es aconsejable que una vez terminada la instalación (puede tardar bastante) se haga un reinicio del ordenador.

Después de reiniciar, habilita el hipervisor:

bcdedit /set hypervisorlaunchtype auto

... y vuelve a reiniciar.

Una vez activada la característica de virtualización WSL, pasamos a instalar una distribución de Linux (Ubuntu):

wsl --install -d Ubuntu

Esto descargará, instalará y configurará Ubuntu en el entorno WSL. Para finalizar te pedirá los datos para dar de alta un usuario y su nueva contraseña para el entorno de la distribución instalada.

Configuración de WSL2

Ahora vamos a establecer WSL2 como predeterminado. Ejecuta:

wsl --set-default-version 2

Inicia una sesión en Ubuntu:

wsl -d Ubuntu

Revisamos que systemd está habilitado inspeccionando el archivo correspondiente:

cat /etc/wsl.conf

El comando nos devolverá el contenido del archivo, que debe ser el siguiente:

[boot]
systemd=true

Si el contenido no es ese, lo editamos con:

sudo nano /etc/wsl.conf

... y lo actualizamos.

Para guardar los cambios salimos con Ctrl+X (te pedirá confirmar el guardado de datos).

El paso final en la configuración de la distribución es reiniciarla, para ello primero salimos:

exit

y, acto seguido paramos la distro. Tienes diferentes maneras de parar la máquina virtual de la distribución Ubuntu:

Una vez realizado el ‘exit’: esperar al menos 8 segundos, después de este lapso de tiempo se habrá parado la distribución.
Realizar un apagado de la distribución:

wsl --terminate Ubuntu

Realizar el shutdown del subsistema WSL:

wsl --shutdown

Esta primera vez optamos por utilizar el shutdown de WSL.

Configurar el consumo de recursos de WSL

Opcionalmente podemos decidir la configuración de la virtualización.

En la consola CMD, crea el archivo:

notepad %UserProfile%\.wslconfig

Y añádele el contenido:

[wsl2]
memory=8GB
processors=4
swap=2GB

Para cambiar los parámetros a tu gusto tienes un enlace a Microsoft Learn al final del artículo.

Instalación de Docker en Ubuntu

Para continuar abrimos una consola Powershell.

A) Verificar uso de systemd en Ubuntu

Accedemos a la terminal de Ubuntu:

wsl -d Ubuntu

Para verificar que el inicio está apuntando a systemd lanzamos el siguiente comando:

stat /sbin/init | grep "systemd"

nos debería dar como resultado:

File: /sbin/init -> ../lib/systemd/systemd

B) Instalar Docker en Ubuntu

Ahora vamos a instalar docker en la distribución Ubuntu (extraído de la web de Docker):

sudo apt update && sudo apt upgrade -y
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER

Comprobamos que se ha instalado:

docker version
docker compose version

C) Configuración del firewall en Ubuntu

El siguiente paso es configurar el firewall en la distribución Ubuntu:

sudo update-alternatives --config iptables

y seleccionamos la opción '1' que corresponde a iptables-legacy.

Enlaces

Docker: https://www.docker.com/ , https://docs.docker.com/engine/install/ubuntu/
Configuración WSL: Advanced settings configuration in WSL | Microsoft Learn

Siguiente artículo:

Docker en Windows. Apartado II: Instalar Docker en Windows 11.

Python. Project Structure (& X)

Raül Martínez i Peris — Sun, 05 Oct 2025 16:40:58 +0000

Índice:

Sección A. Estructurar un proyecto: apartado I, apartado II, apartado III, apartado IV, apartado V, apartado VI, apartado VII, apartado VIII, apartado IX, apartado X.

En este último apartado de la sección "Estructurar un proyecto" hablaremos de la revisión de código en grupo.

La revisión de código es una parte fundamental para el trabajo en grupo en equipos de desarrollo, por ello es necesario tener claros los límites y alcances.

Es imprescindible mantener unas buenas prácticas para que una revisión de código sea un factor de mejora de las interrelaciones del grupo:

El foco tiene que ser estricto: se habla del tema y solo del tema. Después habrá tiempo para otras cosas.
Se revisa el código, nunca se habla de las personas que lo escribieron ni porqué; solo una revisión empática y profesional podrá ser constructiva. Todos deben entender que es un momento para entablar una conversación con la mente abierta y mejorar el trabajo en equipo para el futuro.
Siempre limitamos el tiempo; cuanto más corta más eficaz, cuanto más larga más pesada.
No se realizan a diario, ni semanalmente: solo cuando son necesarias.
Recuerda que: si acudes a la reunión sin haber leído mínimamente el código y el objetivo de la reunión, te convertirás en un troll que destrozará todo el mobiliario y amistades.

Fase 1: preparación

En esta fase nunca revisamos código. ¿Qué se hace?

Definir el alcance: seleccionamos un componente, archivo, módulo, que esté causando errores y que sea crítico para el negocio; o, que por urgencia haya que actuar con celeridad.
Preparar el contexto (y el código involucrado): haremos un breve resumen de qué hace el código, cual es su importancia y los problemas o dudas que se deben resolver. En este punto es habitual tener unas primera preguntas u observaciones sobre las que empezar a hablar.
Acceso al código: debemos asegurarnos que todas las personas del grupo tienen acceso y han podido revisar mínimamente el código para saber sobre qué se va a trabajar.

Fase 2: la reunión

Deben estar limitadas a 30 ó 60 minutos como mucho. No es una reunión para escribir código, es una reunión para encontrar soluciones.
Para evitar las confusiones y desapegos es necesario mantener unas ciertas reglas:
- una persona será el moderador, manteniendo el enfoque en la reunión y asegurándose que todos participen.
- habrá también un presentador (en equipos muy pequeños puede ser el mismo moderador), que se encargará de mostrar el código y explicar las decisiones que llevaron a escribir dicho código; por ello es importante que preferiblemente sea quien escribió el código o alguien que esté al corriente del mismo.
- y los revisores, el resto de personas involucradas en el equipo. Su principal enfoque es repreguntar el código, detectar posible fallos y proponer mejoras.
La sesión la dividiremos en tres partes:
- La introducción, corta (5 minutos o poco más); en ella se explica el objetivo del código y el problema que tenemos o en qué debemos enfocarnos.
- Revisión del código (esta es la parte gruesa del tiempo ocupado), donde se mostrarán las secciones del código explicando su intención y lógica. No se lee el código línea a línea. En consecuenca, surgirán posibles temas de debate:
- Arquitectura. ¿Se repestan los patrones de diseño (SOLID, DRY, etc.)?
- Mantenibilidad. ¿Qué dificultad aporta su diseño para que un nuevo desarrollador que lo desconoce pueda cambiar la lógica del código (refactor)?
- Escalabilidad. ¿Será igualmente eficiente cuando evolucione?
- Test. ¿Es posible simplificar los tests de las funcionalidades afectadas?
- Resultados. Una vez terminada la sesión, el moderador o la persona que se encargara habrá tomado notas y se revisarán en conjunto para clasificar las actuaciones y nombrar un responsable según sean:
- Actuaciones críticas: bugs, seguridad. Saldrá un grupo o persona encargada de que se solucione urgentemente.
- Importantes: diseño o refactorización. Se programará una tarea a futuro con un responsable.
- Mejoras: pequeños retoques o de estilo. Se valorará si el beneficio merece el esfuerzo y tiempo.

Fase 3: seguimiento

El resultado de la reunión quedará por escrito, documentada con una lista de acciones y responsable utilizando la herramienta deseada.

Los responsables designados se encargarán de realizar o establecer los equipos responsables de actuar.

Para el cierre de los tickets/incidencias/refactor (o como se quiera categorizar) es necesario que el presentador de la reunión muestre su conformidad con el resultado obtenido.

Enlaces

Repositorio del proyecto:

https://gitlab.com/elferrer/la_fragua.git

Lecturas de interés:

Clean Code (Robert C. Martin).
Refactoring: Improving the Design of Existing Code (Martin Fowler).
Código sostenible (Carlos Blé).

Python. Project Structure (IX)

Raül Martínez i Peris — Sun, 05 Oct 2025 09:17:36 +0000

Índice:

Sección A. Estructurar un proyecto: apartado I, apartado II, apartado III, apartado IV, apartado V, apartado VI, apartado VII, apartado VIII, apartado IX, apartado X.

En este artículo daremos un breve paseo a las particularidades de los archivos involucrados en la generación de la aplicación .exe.

Archivos involucrados

Como hemos visto en el artículo anterior (apartado VIII), hemos creado una batería de archivos para conseguir generar el .exe:

.gitlab-ci.yml, tarea launch-build-exe: lanzador en el pipeline de Gitlab de la Action de GitHub
ci/github-build.yml: Action de GitHub.
app/main.spec: especificaciones para la generación del .exe.
extra-hooks/hook-pydantic.py: módulos y submódulos de pydantic.

Lanzamiento de la Action de GitHub

Empezamos por el principio: lo primero que ocurrirá es que el pipeline de Gitlab provocará el lanzamiento de la Action de GitHub:

En la tarea launch-build-exe realizamos lo siguiente:

En before_script añadimos los paquetes necesarios y copiamos los archivos .env.
Comprimimos el repositorio (excepto los archivos innecesarios).
Configuramos git.
Hacemos un clonado del repositorio de GitHub y borramos su contenido (con el fin posterior de actualizar su contenido).
Descomprimimos el 'zip' en la carpeta del proyecto clonado.
Añadimos dinámicamente el workflow para GitHub y limpiamos la carpeta origen (ci)
El último paso es hacer un commit y un push para actualizar el repo de GitHub y desencadenar la construcción.

Como última nota a este punto cabe destacar que solo se disparará la acción si se cumplen las condiciones establecidas.

Ejecución de la Action en GitHub

En el instante en que se actualiza el repositorio en GitHub se desencadena la Action que se encuentra .github/workflows. En el 'github-build' podemos ver los siguientes pasos:

Realizamos un checkout del repositorio.
Confirmamos que tenemos el archivo .env.production de producción. Si no existiera se daría por finalizado la Action.
Preparamos el entorno Python: instalación de Python, creación del entorno virtual venv, actualización de pip, instalar dependencias manualmente (por si alguna biblioteca no se instala automáticamente), instalar dependencias de requirements, instalar pyinstaller y las bibliotecas para los hook
Verificamos que los paquetes necesarios se han instalado.
Instalamos WebView2 runtime (para pywebview) descargándolo de la URL de Microsoft.
Compilamos la aplicación con PyInstaller, copiamos las DLL's necesarias y plugins de Qt6 a la carpeta dist.
Y, como punto final, publicamos el artefacto y generamos un tag.

Generación del `.exe` con PyInstaller

En el archivo main.spec tenemos las especificaciones detalladas de cómo se va a compilar la aplicación.

Sin embargo, necesitamos que los módulos de nuestra aplicación estén disponibles, por lo que utilizamos un hook personalizado (archivo hook-pydantic.py) que se encargará de incluir explícitamente todos los submódulos de pydantic y pydantic_settings en la lista de importaciones ocultas. De esta forma evitamos que la compilación falle por falta de librerías.

Veamos las fases según nuestro main.spec.

Recolección y preparación de archivos

Recogemos los datas necesarios. Para ello tenemos la función collect_all_data con la que recorremos recursivamente la carpeta app y añadimos todos los archivos necesarios a la colección de datas.

Añadimos las dependencias de sistema para incluirlas en el .exe, buscamos y añadimos las DLL's de: site_packages, qt6_base, qt_bin y qt_plugins.

Añadimos los recursos de NiceGUI: archivos static y las templates.

Añadimos nuestro archivo de configuración .env.production.

Añadimos un icono si existe (app/assets/icon.ico).

Y añadimos las importaciones ocultas con hiddenimports recolectadas por el hook.

Análisis y empaquetado

Ahora que tenemos todos los archivos, vamos a construir el paquete siguiendo los siguientes pasos:

Análisis: analizamos app/main.py, los datas, las importaciones ocultas, y generamos los metadatos. Puedes ver que incluimos los PyQt6 manualmente.
Empaquetado: comprimimos el código fuente de Python y los módulos en un archivo .pyz.
Crear el ejecutable: creamos el ejecutable, que incluye el archivo .pyz del empaquetado, los bootloaders de PyInstaller, las propiedades (nombre, icono, compresión UPX, habilitado de la consola)
Ensamblaje final: se prepara la carpeta dist y se incluyen el .exe, empaquetados del source code así como todo lo que fuera necesario.

La parte que suele dar más quebraderos de cabeza suele ser la de los hiddenimports.

Apuntes

Hay que tener en cuenta que este empaquetado es muy básico y solo incluye las necesidades mínimas. Tal como vaya creciendo la aplicación habrá que ir actualizando el guión de preparación del ejecutable.

Enlaces

Repositorio del proyecto:

https://gitlab.com/elferrer/la_fragua.git

Enlaces de interés:

Uso de PyInstaller: https://pyinstaller.org/en/stable/usage.html#options-group-what-to-bundle-where-to-search
Utilización de archivos .spec: https://pyinstaller.org/en/stable/spec-files.html
Sobre los hook: https://pyinstaller.org/en/stable/hooks.html
Empaquetado de NiceGUI: https://nicegui.io/documentation/section_configuration_deployment#package_for_installation

Siguiente artículo:

Sección A. Estructurar un proyecto: apartado X: Revisión de código, trabajo en equipo.

Python. Project Structure (VIII)

Raül Martínez i Peris — Sat, 04 Oct 2025 15:35:23 +0000

Índice:

Sección A. Estructurar un proyecto: apartado I, apartado II, apartado III, apartado IV, apartado V, apartado VI, apartado VII, apartado VIII, apartado IX, apartado X.

Para crear la aplicación .exe para Windows, vamos a necesitar lanzar PyInstaller a través de GitHub Actions.

¿Porqué GitHub? GitHub nos permite lanzar gratuitamente hasta 2.000 minutos de cómputo, incluyendo también una FreeTier de Windows.

¿Porqué no se hizo todo con GitHub? La mejor forma de aprender cómo integrar diferentes plataforma es haciéndolo, por lo que aprovechamos que ambas plataformas tienen planes gratuitos para mostrar como integrarlas.

Preparar el repositorio de GitHub

Vamos a GitHub y creamos un nuevo repositorio para lanzar el pipeline.

Una vez creado el repositorio, en el icono de usuario (arriba a la derecha) pulsa Settings en el desplegable.

Nos aparecerá a la izquierda, al final de todos los settings (abajo), el apartado Developer setting, tras abrir Personal access tokens pulsamos sobre Tokens (clasic) y nos creamos un nuevo token haciendo click en:

Generate new token > Generate new token (classic), y rellenamos:
- Note: ponemos un alias identificativo.
- Expiration: seleccionamos cuanto tiempo queremos que dure.
- Select scopes, seleccionamos los siguientes:
- repo (todos)
- workflow
Pulsamos en Generate token.

Atención: Únicamente nos mostrará una vez el token, nunca volverás a verlo, guárdalo en tu almacén de contraseñas.

Preparación de los pipelines

En esta parte vamos a indicar los archivos necesarios, pero será en el artículo siguiente donde haremos una breve explicación de las partes interesantes a tener en cuenta.

Añadimos a nuestro repo los siguientes archivos:

Actualizamos requirements-extra-windows.txt añadiendo:

PyInstaller

Creamos el 'github-build' que necesitaremos para GitHub:

# ci/github-build.yml
name: Build EXE

on:
  push:
    branches:
      - __BUILD_BRANCH__

permissions:
  contents: write

jobs:
  build:
    runs-on: windows-latest
    steps:
      # 1. Clonar el repositorio
      - name: Checkout project
        uses: actions/checkout@v4

      # 2. **Verificación entorno**
      - name: Check for .env.production file
        id: check_env
        shell: pwsh
        run: |
          if (-not (Test-Path ".env.production")) {
            Write-Error "Error: No existe el archivo '.env.production'. Recuerde que la aplicación se genera con el entorno de producción."
            exit 1
          }

      # 3. Instalar Python 3.12
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      # 4. Crear y activar entorno virtual
      - name: Create virtual environment
        shell: pwsh
        run: |
          python -m venv venv
          .\venv\Scripts\Activate.ps1
          python -m pip install --upgrade pip wheel setuptools

      # 5. Instalar dependencias dentro del venv
      - name: Install dependencies
        shell: pwsh
        run: |
          .\venv\Scripts\Activate.ps1
          # Instalación de requisitos explícitos
          pip install PyQt6 PyQt6-WebEngine
          pip install nicegui
          pip install pydantic-settings
          pip install pydantic
          pip install pywebview
          # Resto de requisitos
          pip install -r requirements.txt -r requirements-extra-windows.txt
          # PyInstaller al final
          pip install pyinstaller
          pip install --upgrade pyinstaller pyinstaller-hooks-contrib

      # 6. Verificar paquetes instalados
      - name: Verify key packages
        shell: pwsh
        run: |
          .\venv\Scripts\Activate.ps1
          python -c "import PyQt6; print('PyQt6 OK')"
          python -c "import PyQt6.QtWebEngineWidgets; print('WebEngineWidgets OK')"
          python -c "import nicegui; print('NiceGUI OK')"

      # 7. Comprobar DLLs de Qt6
      - name: Verify Qt6 DLLs
        shell: pwsh
        run: |
          .\venv\Scripts\Activate.ps1
          $pyqt6_path = (python -c "import PyQt6; print(PyQt6.__path__[0])")
          $qt6_base = Join-Path $pyqt6_path "Qt6"
          if (Test-Path "$qt6_base\bin") { echo "Qt6 bin exists"; dir "$qt6_base\bin" } else { echo "Qt6 bin not found" }
          if (Test-Path "$qt6_base\plugins") { echo "Qt6 plugins exist"; dir "$qt6_base\plugins" } else { echo "Qt6 plugins not found" }

      # 8. Instalar WebView2 runtime (para pywebview)
      - name: Install WebView2 runtime
        shell: pwsh
        run: |
          Invoke-WebRequest -Uri "https://go.microsoft.com/fwlink/p/?LinkId=2124703" -OutFile "MicrosoftEdgeWebView2Setup.exe"
          write-host "Lanzando MicrosoftEdgeWebView2Setup.exe en modo desatentido (silent)..."
          Start-Process .\MicrosoftEdgeWebView2Setup.exe -ArgumentList "/silent","/install" -Wait

      # 9. Compilar con PyInstaller
      - name: Compile app
        shell: pwsh
        run: |
          .\venv\Scripts\Activate.ps1
          pyinstaller app/main.spec --noconfirm
          echo "Build finished. Checking dist/"
          dir dist

      # 10. Copiar DLLs y plugins de Qt6 al dist
      - name: Copy Qt6 runtime dependencies
        shell: pwsh
        run: |
          .\venv\Scripts\Activate.ps1
          $pyqt6_path = (python -c "import PyQt6; print(PyQt6.__path__[0])")
          $QT6_PATH = Join-Path $pyqt6_path "Qt6"
          $DEST = "dist\la_fragua"
          Write-Host "Copying Qt6 from $QT6_PATH to $DEST"
          Copy-Item "$QT6_PATH\bin\*.dll" -Destination "$DEST\PyQt6\Qt6\bin" -Recurse -Force -ErrorAction SilentlyContinue
          Copy-Item "$QT6_PATH\plugins" -Destination "$DEST\PyQt6\Qt6" -Recurse -Force -ErrorAction SilentlyContinue
          Copy-Item "$QT6_PATH\resources" -Destination "$DEST\PyQt6\Qt6" -Recurse -Force -ErrorAction SilentlyContinue
          if (Test-Path "$QT6_PATH\translations") {
            Copy-Item "$QT6_PATH\translations" -Destination "$DEST\PyQt6\Qt6" -Recurse -Force
          }

      # 11. Publicar artefacto en release
      - name: Release build artifact
        uses: softprops/action-gh-release@v1
        with:
          tag_name: "__BUILD_BRANCH__-${{ github.run_number }}"
          generate_release_notes: true
          files: dist/*.exe
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Ahora necesitamos crear el archivo spec para la configuración de creación del .exe:

# app/main.spec
# main.spec para compilación en windows
# -*- mode: python ; coding: utf-8 -*-

import os
import sys
import PyQt6
import PyQt6.QtWebEngineWidgets
import nicegui
from PyInstaller.utils.hooks import collect_all, collect_data_files, collect_submodules

# ---- Carpeta base del proyecto ----
project_dir = os.getcwd()
app_dir = os.path.join(project_dir, "app")
hookspath = [os.path.join(project_dir, 'extra-hooks')]

# ---- Recolectar archivos del proyecto ----
def collect_all_data(src_folder):
    datas = []
    for root, dirs, files in os.walk(src_folder):
        for file in files:
            if file.endswith('.pyc') or file.endswith('.env.production'):
                continue
            full_path = os.path.join(root, file)
            rel_path = os.path.relpath(root, src_folder)
            target_path = os.path.join(rel_path)
            datas.append((full_path, target_path))
    return datas

datas = collect_all_data(app_dir)

# ---- Qt6 DLLs y plugins ----
site_packages = sys.base_prefix + r"\Lib\site-packages"
qt6_base = os.path.join(site_packages, "PyQt6", "Qt6")

# DLLs (bin)
qt_bin = os.path.join(qt6_base, "bin")
if os.path.exists(qt_bin):
    datas += [(os.path.join(qt_bin, f), "PyQt6/Qt6/bin") for f in os.listdir(qt_bin) if f.endswith(".dll")]

# Plugins (platforms, imageformats, etc.)
qt_plugins = os.path.join(qt6_base, "plugins")
for root, dirs, files in os.walk(qt_plugins):
    for file in files:
        full_path = os.path.join(root, file)
        rel_path = os.path.relpath(root, qt6_base)
        datas.append((full_path, f"PyQt6/Qt6/{rel_path}"))

# ---- NiceGUI recursos estáticos ----
datas += collect_data_files("nicegui", subdir="static")
datas += collect_data_files("nicegui", subdir="templates")

# Aquí cambiamos a .env.production
datas += [(os.path.join(project_dir, '.env.production'), '.')]

# ---- Icono opcional ----
icon_path = os.path.join(app_dir, 'assets', 'icon.ico')
if not os.path.exists(icon_path):
    icon_path = None

# ---- Recoger todos los submódulos para pydantic y pydantic_settings ----
hidden_imports = collect_submodules('pydantic') + collect_submodules('pydantic_settings') + ["PyQt6.QtWebEngineWidgets"]

# ---- Análisis ----
a = Analysis(
    [os.path.join(app_dir, "main.py")],
    pathex=[project_dir],
    binaries=[],
    datas=datas,
    hiddenimports=[
        "PyQt6.QtWebEngineWidgets",
        "PyQt6.QtWebEngineCore",
        "PyQt6.QtWebChannel",
        "PyQt6.QtPositioning",
    ] + hidden_imports,
    hookspath=hookspath,
    runtime_hooks=[],
    excludes=[],
    win_no_prefer_redirects=False,
    win_private_assemblies=False,
    cipher=None,
    noarchive=False,
)

pyz = PYZ(a.pure, a.zipped_data, cipher=None)

exe = EXE(
    pyz,
    a.scripts,
    a.binaries,
    a.zipfiles,
    a.datas,
    name="la_fragua.exe",
    debug=False,
    strip=False,
    upx=True,
    console=True,
    icon=icon_path,
)

coll = COLLECT(
    exe,
    a.binaries,
    a.zipfiles,
    a.datas,
    strip=False,
    upx=True,
    name="la_fragua",
)

También necesitamos el archivo 'hook-pydantic':

# extra-hooks/hook-pydantic.py
from PyInstaller.utils.hooks import collect_submodules

hiddenimports = collect_submodules('pydantic') + collect_submodules('pydantic_settings')

Y finalmente, añadimos a 'gitlab-ci' el stage necesario (línea 3-4):

  - build

a continuación del stage 'test' le agregamos una nueva tarea:

launch-build-exe:
  stage: build
  image: alpine:latest
  before_script:
    - apk add --no-cache git zip unzip curl bash
    - curl --silent "https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/download-secure-files/-/raw/main/installer" | bash
    # descarga de los archivos protegidos
    - download-secure-files
    - cp .secure_files/.env .
    - cp .secure_files/.env.production .
  script:
    # empaquetar el código excluyendo .git
    - zip -r project.zip . -x ".git/*" -x "tests/*" -x "KANBAN.md" -x "README.md" -x ".gitlab-ci.yml" -x ".gitignore"

    # configurar git
    - git config --global user.email "$GITLAB_CI_EMAIL"
    - git config --global user.name "$GITLAB_CI_USER"

    # clonar el repo de GitHub
    - git clone https://oauth2:${GITHUB_TOKEN}@github.com/${GITHUB_USER}/${GITHUB_REPO}.git
    - cd ${GITHUB_REPO}
    - git checkout -B $BUILD_BRANCH
    - rm -rf *

    # mover proyecto
    - mv ../project.zip .
    - unzip project.zip
    - rm project.zip

    # añadir workflow con datos dinámicos
    - mkdir -p .github/workflows
    - sed -e "s|__BUILD_BRANCH__|$BUILD_BRANCH|g" -e "s|__CI_PROJECT_NAME__|$CI_PROJECT_NAME|g" ./ci/github-build.yml > .github/workflows/build.yml
    - mv ./ci/README.github.md README.md
    - rm -r ./ci

    # commit & push
    - git add .
    - git commit -m "Trigger build from GitLab CI ${BUILD_BRANCH}"
    - git push origin $BUILD_BRANCH --force
  rules:
    - if: '$CI_COMMIT_BRANCH == "main" && $CI_COMMIT_MESSAGE =~ /^\[build-exe\]/'
      when: always
    - when: manual
  allow_failure: true

Configuración del entorno de Gitlab

Una vez actualizados los ficheros preparamos el entorno de Gitlab. Para ello, desde Gitlab:

Settings > CI/CD Settings > CI/CD Variables, añadimos la variables:
- BUILD_BRANCH (contenido: un nombre descriptivo para tu rama en GitHub)
- GITHUB_REPO (contenido: el nombre de tu repositorio en GitHub)
- GITHUB_USER (contenido: tu usuario de GitHub)
- GITLAB_CI_EMAIL (contenido: tu correo electronico)
- GITLAB_CI_USER (contenido: un alias descriptivo)
- GITHUB_TOKEN (contenido: tu token de GitHub)
Actualizamos/añadimos los archivos protegidos:
- Settings > CI/CD Settings > Secure files:
- .env
- .env.production

Una vez que has configurado totalmente las variables y archivos protegidos, ya puedes subir la rama a Gitlab:

git add .
git commit -m 'Virtualización'
git push -u origin 'release/000-virtualization'

Volvemos a Gitlab realizamos el Merge Request y lo fusionamos.

Una vez terminado solo nos queda actualizar nuestra rama local de 'main':

git checkout main
git pull

Comprobación

Si todo ha funcionado correctamente, en tu cuenta de GitHub se habrá lanzado una Action sobre tu repositorio, que te habrá generado un artefacto y un tag a dicho artefacto.

Para ver el artefacto debes pinchar sobre "Tag" y una vez dentro verás que también tienes "Releases", dentro de las cuales están los artefactos generados.

Apuntes

En BUILD_BRANCH puedes poner, por ejemplo: 'el_repositorio-build_artifact'.
En GITLAB_CI_EMAIL, puedes poner tu email o puedes utilizar un email que te indica GitHub. Lo tienes en los Settings de usuario, en el apartado Emails > Keep my email addresses private, donde tras activarlo leerás en la explicación "We'll remove your public profile email and use [...@users.noreply.github.com]".

Enlaces

Repositorio del proyecto:

https://gitlab.com/elferrer/la_fragua.git

Siguiente artículo:

Sección A. Estructurar un proyecto: apartado IX: Comentarios sobre la creación del .exe de Windows.

Python. Project Structure (VII)

Raül Martínez i Peris — Sat, 04 Oct 2025 15:19:19 +0000

Índice:

Sección A. Estructurar un proyecto: apartado I, apartado II, apartado III, apartado IV, apartado V, apartado VI, apartado VII, apartado VIII, apartado IX, apartado X.

Como hemos comentado en anteriormente, hemos cometido un par de errores en los archivos Dockerfile.

Ahora debemos corregirlo, pero, queremos hacerlo en la rama correspondiente y llevar los cambios a main.

¿Qué ocurre si no estamos en un estado 'limpio'?

Antes de continuar, como es habitual, debes estar sin ningún cambio en el repositorio: nunca debes empezar a trabajar teniendo código a medias, en ninguna rama.

Si estás trabajando y surge una urgencia que te obliga a dejar a medias un trabajo, tienes varias opciones:

Guardar el trabajo para continuar después sin ensuciar el histórico. Esta es la mejor opción.
Descartar lo trabajado.
Crear un commit (indicando claramente que el trabajo no está terminado). Esto es una mala opción.

Veamos la opción 1, cómo guardar el trabajo sin hacer commit:

git add .
git stash

Esto realiza un 'commit interno' que no existe en el histórico de las ramas.

Para consultar los commit internos que tienes en stash:

git stash list

Para recuperar el último commit interno que tienes en el stash:

git stash apply

Hay más opciones muy interesantes, revisa la documentación de git.

Sincronizar la copia local

Sabiendo que no tenemos código a medias, lo primero es tener actualizadas las ramas involucradas.

Nos situamos en main y la actualizamos:

git checkout main
git pull

Nos situamos en release/000-virtualization y la actualizamos:

git checkout 'release/000-virtualization'
git pull

Realizar los cambios y hacer el commit

Ahora realizaremos las correcciones de los errores que cometimos.

En el archivo Dockerfile:

Busca APP_FOLDER y sustituyelo por APP_PATH.

En el archivo Dockerfile.windows:

Busca APP_FOLDER y sustituyelo por APP_PATH.
Busca APP_VIRTUALIZATION y sustituyelo por APP_ENV.

Ahora realizamos el commit:

git add .
git commit -m 'Correcciones en los archivos Dockerfile'

Preparar la rama y subir los cambios

Primero nos traemos la rama main a la nuestra:

git merge main

Si existe algún conflicto git te lo avisará. Si esto ocurre tendrás que resolverlo, y hacer un nuevo commit.

Ahora debemos subir los cambios a origin:

git push origin 'release/000-virtualization'

Te estarás preguntando porqué hicimos el merge después de hacer los cambios y el commit. La explicación es sencilla: queremos tener en nuestra rama lo último que entró en main porque después debemos realizar el merge request y para que no haya problemas añadidos deberíamos tener lo último. Por ello, cuanto más tiempo pasa entre tu merge de main y tu push a origin , más posibilidades de que no sea lo último. Yo personalmente hago un merge antes de empezar y otro después, lo cual me garantiza trabajar sobre lo último y asegurarme que es lo último con lo que hago la petición de MR.

Crear el Merge Request

Esta parte ya sabes como funciona, lo vimos en un artículo anterior. Haz el MR y después descárgate a main los cambios.

Apuntes

Merge vs Rebase

En git hay una regla de oro: nunca hagas un rebase en ramas compartidas o públicas.

Estas son las razones:

Preservación del historial (acción no destructiva): con git merge preservamos el historial de forma cronológica y real.
Seguridad en el trabajo en equipo: la utilización de git merge no reescribe los commit por lo que es fácil llevar un seguimiento rápido y limpio. Sin embargo, el uso de git rebase reescribe el historial de la rama, por lo que en cualquier otro clonado existente del repositorio los ID's de los commits serán diferentes, provocando en el resto del equipo un considerable costo de tiempo revisando lo ocurrido.
Claridad en las auditorías de código: cuando utilizamos git merge, la utilización de herramientas como git bisect se facilita enormemente al mostrar exactamente qué ocurrió y cuando.

Enlaces

Repositorio del proyecto:

https://gitlab.com/elferrer/la_fragua.git

Enlaces de interés:

Sobre los entornos: en https://gitlab.com/elferrer/la_fragua/-/blob/main/README.md?ref_type=heads#docker-compose encontrarás información sobre cómo utilizar los diferentes entornos de desarrollo/producción en Linux/Windows.
Git stash: https://git-scm.com/docs/git-stash

Siguiente artículo:

Sección A. Estructurar un proyecto: apartado VIII: Creación del .exe de Windows.

Python. Project Structure (VI)

Raül Martínez i Peris — Sat, 04 Oct 2025 15:04:11 +0000

Índice:

Sección A. Estructurar un proyecto: apartado I, apartado II, apartado III, apartado IV, apartado V, apartado VI, apartado VII, apartado VIII, apartado IX, apartado X.

En este apartado crearemos lo necesario para trabajar con la virtualización de entornos.

Crear una nueva rama

Empezamos con la creación de la rama release/000-virtualization:

git checkout -b 'release/000-virtualization'

Ahora actualizamos el archivo .gitignore añadiendo:

.env.production

Docker

Empezaremos añadiendo el archivo .dockerignore:

_temp_/
.git
.gitignore
.env*
.vscode/
.venv/
.pytest*
tests/
Dockerfile
compose.yml
compose.override.yml

Ahora prepararemos los entornos para Linux y Windows por separado.

Docker en el entorno Linux

Creamos el archivo Dockerfile:

# Dockerfile
FROM python:3.12-slim AS base

# Configuración de entorno
ARG APP_PATH=/opt/la_fragua
ENV APP_PATH=${APP_PATH}
ARG APP_ENV=production
ENV APP_ENV=${APP_ENV}
ARG APP_PORT=8080
ENV APP_PORT=${APP_PORT}

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    POETRY_VIRTUALENVS_CREATE=false \
    PATH="/root/.local/bin:$PATH" \
    DISPLAY=:99 \
    QT_QPA_PLATFORM=offscreen

# Crear directorio de la aplicación
WORKDIR ${APP_PATH}

# Instalar dependencias del sistema necesarias para nicegui (qt, chrome, etc.)
RUN apt-get update && apt-get install -y \
    git curl build-essential \
    libglib2.0-0 libnss3 libx11-6 libxcomposite1 \
    libxdamage1 libxrandr2 libxkbcommon0 libxshmfence1 \
    libasound2 libatk1.0-0 libatk-bridge2.0-0 libcups2 \
    libdrm2 libxext6 libgbm1 libxfixes3 libxrender1 \
    xvfb x11vnc fluxbox wmctrl \
    && rm -rf /var/lib/apt/lists/*

# ---- desarrollo ----
FROM base AS dev
COPY requirements.txt .
COPY requirements-dev.txt .
RUN pip install --upgrade pip && pip install -r requirements.txt -r requirements-dev.txt
CMD ["python3", "-m", "app.main"]

# ---- producción ----
FROM base AS production
COPY requirements.txt .
RUN pip install --upgrade pip && pip install -r requirements.txt
COPY . ${APP_FOLDER}
EXPOSE ${APP_PORT}
RUN echo '#!/bin/bash\nXvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &\npython3 -m app.main' > /opt/start.sh && \
    chmod +x /opt/start.sh
CMD ["/opt/start.sh"]

Una vez que tenemos el archivo Dockerfile vamos a preparar los archivos 'compose' para automatizar la creación y ejecución de los entornos.

Creamos el archivo compose.yml:

# compose.yml para producción
services:
  la_fragua:
    image: "${DOCKER_LOGIN}/${APP_NAME}-linux:latest"
    build:
      context: .
      dockerfile: "Dockerfile"
      target: production
    env_file:
      - .env.production
    ports:
      - "${APP_PORT}:8080"
    environment:
      - APP_ENV=container
      - APP_PATH=/opt/la_fragua
    restart: always

Creamos el archivo compose.override.yml:

# compose.override.yml para dev
services:
  la_fragua:
    image: "${APP_NAME}-linux:dev"
    build:
      context: .
      dockerfile: "Dockerfile"
      target: dev
    env_file:
      - .env
    ports:
      - "${APP_PORT}:8080"
    environment:
      - APP_ENV=container
      - APP_PATH=/opt/la_fragua
    volumes:
      - .:/opt/la_fragua
    stdin_open: true
    tty: true

Docker en el entorno Windows

Añadimos al archivo .dockerignore el siguiente contenido:

Dockerfile.windows
compose.windows.yml
compose.windows.override.yml

Creamos el archivo Dockerfile.windows:

# Dockerfile.windows
FROM mcr.microsoft.com/windows/servercore:ltsc2022 AS base

# Shell Powershell
SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop';"]

# Instalar Python
RUN Invoke-WebRequest -UseBasicParsing https://www.python.org/ftp/python/3.12.0/python-3.12.0-amd64.exe -OutFile python-installer.exe; \
    Start-Process python-installer.exe -Wait -ArgumentList '/quiet', 'InstallAllUsers=1', 'PrependPath=1', 'DefaultAllUsersTargetDir=C:\Python312'; \
    Remove-Item python-installer.exe -Force

# Actualizar pip
RUN python -m pip install --upgrade pip --disable-pip-version-check

# Configuración de entorno
ARG APP_PATH="C:/la_fragua"
ENV APP_PATH=${APP_PATH}
ARG APP_ENV=production
ENV APP_ENV=${APP_ENV}
ARG APP_PORT=8080
ENV APP_PORT=${APP_PORT}

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    APP_VIRTUALIZATION=container \
    QT_QPA_PLATFORM=minimal

# Crear directorio de la aplicación
WORKDIR ${APP_PATH}

# ---------- Dev stage ----------
FROM base AS dev
COPY requirements.txt .
COPY requirements-dev.txt .
RUN pip install --no-cache-dir -r requirements.txt -r requirements-dev.txt
CMD ["python", "-m", "app.main"]

# ---------- Production stage ----------
FROM base AS production
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . ${APP_FOLDER}
EXPOSE ${APP_PORT}
CMD ["python", "-m", "app.main"]

Creamos el archivo compose.windows.yml

# compose.windows.yml para producción
services:
  la_fragua:
    image: "${DOCKER_LOGIN}/${APP_NAME}-windows:latest"
    build:
      context: .
      dockerfile: "Dockerfile.windows"
      target: production
    env_file:
      - .env.production
    ports:
      - "${APP_PORT}:8080"
    environment:
      - APP_ENV=container
      - APP_PATH="C:/la_fragua"
    restart: always

Creamos el archivo compose.windows.override.yml

# compose.windows.override.yml para dev
services:
  la_fragua:
    image: "${APP_NAME}-windows:dev"
    build:
      context: .
      dockerfile: "Dockerfile.windows"
      target: dev
    env_file:
      - .env
    ports:
      - "${APP_PORT}:8080"
    environment:
      - APP_ENV=container
      - APP_PATH="C:/la_fragua"
    volumes:
      - .:C:/la_fragua
    stdin_open: true
    tty: true

Ya tenemos preparados los entornos docker de Linux y Windows.

Hemos cometido un par de errores en los Dockerfile para obligarnos a realizar una corrección. En el siguiente artículo trabajaremos sobre ello.

Apuntes

En los archivos Dockerfile habrás visto que utilizamos FROM python:3.12-slim AS base al inicio, y posteriormente FROM base AS dev y FROM base AS production. Esto, unido al target de los archivos compose nos define qué parte del Dockerfile está generándose. Con esta dinámica hemos conseguido no repetir información en innecesariamente. En el siguiente artículo continuamos trabajando sobre los entornos.

En los archivos compose verás que en producción tenemos la variable DOCKER_LOGIN pero en desarrollo no lo está. Esto tiene una razón: la imagen docker que se genere para producción querremos poder llevarla al hub de docker, pero la imagen de desarrollo no debemos llevarla nunca al hub.

Enlaces

Repositorio del proyecto:

https://gitlab.com/elferrer/la_fragua.git

Enlaces de interés:

Multi-stage builds: https://docs.docker.com/build/building/multi-stage/
Merge Compose files: https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/

Siguiente artículo:

Sección A. Estructurar un proyecto: apartado VII: Corregir errores y no morir en el intento.