Guia completa per crear entorns amb WSL2 + Docker + VS Code

Si treballes a Windows i vols un entorn de desenvolupament sòlid amb Linux, contenidors i editor modern, WSL2, Docker i VS Code formen un trio guanyador. Aquest combo permet programar a Linux sense abandonar Windows, executar contenidors de forma àgil i depurar projectes amb comoditat, tot a la mateixa màquina.

La idea és senzilla: aprofitar el nucli Linux de WSL2, afegir Docker (ja sigui mitjançant Docker Desktop o instal·lant el motor nadiu a la distro) i rematar amb VS Code i Dev Containers per obtenir entorns reproduïbles. A les següents seccions veuràs pas a pas com muntar-lo, amb recomanacions pràctiques, dreceres, casos reals i solucions a problemes típics.

Contenidors i per què encaixen amb WSL2 + VS Code

Docker permet empaquetar aplicacions amb tot el necessari perquè s'executin igual a qualsevol màquina. Davant d'una VM tradicional, els contenidors comparteixen el nucli del host, arrenquen més ràpid i consumeixen menys. A més, faciliten la disponibilitat contínua: puges una nova versió del contenidor i substitueixes sense parar el sistema sencer.

Amb WSL2, Windows porta un nucli Linux real integrat. Gràcies a això, els contenidors Linux funcionen de forma nativa al teu equip, i si fas servir Docker Desktop amb backend WSL 2 pots executar contenidors Linux i Windows costat a costat. Això combina rendiment, compatibilitat i flux de treball unificat.

Requisits i preparació del sistema

Abans de res, convé verificar que Windows compleix els requisits per a WSL2 i Docker Desktop. Revisa les versions i build de Windows (Win + R, escriu winver) i tingues present que Docker Desktop té requisits de sistema i llicència específics (gratuït per a ús personal i petites empreses).

Per instal·lar WSL2 amb el mètode simplificat, obre PowerShell o CMD amb permisos i executa wsl --install. Aquesta ordre habilita els components necessaris, instal·la el kernel Linux, estableix WSL 2 com a predeterminat i descarrega Ubuntu per defecte. Reinicia quan ho demani.

Després de la instal·lació, obre la distro (Ubuntu si no has canviat) i crea la teva usuari i contrasenya de Linux. Recordeu que mentre escriviu la contrasenya no veureu caràcters: és normal. Aquest compte serà el predeterminat i podrà executar suo per a tasques administratives.

Mantingues la distro al dia amb sudo apt update && sudo apt upgrade. Windows no actualitza automàticament la distribució, així que tu decideixes quan. Si vols afegir més distros, pots fer-ho des de Microsoft Store o important imatges.

Terminal, emmagatzematge i editor: primeres decisions

Instal·la Windows Terminal per a una experiència moderna amb pestanyes, panells i temes. Gestiona diverses línies de ordres sense dolor i personalitza al teu gust. Cada vegada que sumes una distro de WSL, apareixerà el seu perfil corresponent al terminal.

Pel que fa als fitxers del projecte, és clau el rendiment: si utilitzeu eines Linux, desa els projectes al sistema de fitxers de WSL2 (Per exemple, \\wsl$\Ubuntu-22.04\home\tuusuario\proyecto). S'hi pot accedir des dels dos costats, però treballar a /mnt/c amb eines Linux pot ser més lent.

Per obrir la carpeta actual de WSL a l'Explorador, executeu explorer.exe . (inclou el punt). I per obrir la carpeta a VS Code des de WSL, utilitza code .. Amb l'extensió correcta, VS Code es connecta al servidor d'extensions dins de WSL i t'oblides de rutes estranyes i problemes de binaris.

Instal·lar Docker Desktop amb backend WSL 2

Una ruta molt còmoda és fer servir Docker Desktop. Descarrega'l, instal·la'l i activa «Use the WSL 2 based engine» a Configuració > General. Després, a Configuració > Resources > WSL Integration, tria les distros WSL2 on vols habilitar la integració.

Verifica la instal·lació des del teu distro amb docker --version i prova amb docker run hello-world. Si tot està bé, tindràs contenidors Linux corrent sobre el nucli de WSL2 i gestionats per Docker Desktop a Windows.

Docker Desktop crea dues distribucions especials de WSL per a emmagatzematge i servei: docker-desktop y docker-desktop-data. També veuràs les seves rutes com \\wsl$\docker-desktop y \\wsl$\docker-desktop-data. Si necessites localitzar les seves dades des de Windows, pots obrir una intèrpret d'ordres WSL i executar explorer.exe ., o navegar a \\wsl\<Distro>\mnt\wsl.

Si veniu d'una vista prèvia antiga de Docker per a WSL, potser quedi un context en desús anomenat «wsl». Comprova-ho amb docker context ls; si apareix, elimina-ho amb docker context rm wsl per evitar errors com «open \\.\/pipe\/docker_wsl». A la integració actual has d'usar el context per defecte.

Desenvolupar en contenidors remots amb VS Code

Per treballar de forma còmoda amb contenidors, instal·la a VS Code les extensions WSL, Dev Containers y estibador. Amb elles, podràs obrir el teu projecte WSL a VS Code, ia més reobrir la carpeta dins un contenidor de desenvolupament amb tot el stack llest.

Exemple pràctic (Django). Des del vostre terminal WSL clona un repositori, com el d'un “Hello World” de Django: git clone https://github.com/mattwojo/helloworld-django.git, entra amb cd helloworld-django i obre VS Code amb code .. Comproveu l'indicador verd de connexió remota a WSL a la part inferior esquerra.

Obre la paleta (Ctrl + Maj + P) I triï “Dev Containers: Reopen in Container” (o “Open Folder in Container…” si vens des de Windows mitjançant \\wsl$). Selecciona una definició adequada (per exemple, Python 3 per a Django). VS Code generarà una carpeta .devcontainer amb Dockerfile y devcontainer.json, construirà la imatge i aixecarà el contenidor de desenvolupament.

Obre el terminal integrat i executa uname per confirmar que ets a Linux, i python3 --version per veure la versió de Python del contenidor. Per depurar, vés a la vista Executar i Depurar, crea el launch.json triant la configuració del framework (Django en aquest cas) i prem F5. Obre la URL que t'indiqui el terminal (per exemple, http://127.0.0.1:8000).

Dev Containers i Codespaces: entorns reproduïbles

Un Dev Container es defineix amb .devcontainer/devcontainer.json i, opcionalment, un Dockerfile. Aquest enfocament permet utilitzar imatges base o altres personalitzades, preinstal·lar dependències, configurar extensions de VS Code i automatitzar ordres post-configuració.

Entre els casos d'ús més comuns hi ha els de Data Science col·laboratiu (amb Python, Jupyter, pandes, seaborn i un conjunt homogeni de dependències) i els de backend Node.js amb PostgreSQL coordinats amb docker-compose.yml. D'aquesta manera tot l'equip treballa amb el mateix entorn, sense sorpreses per diferències locals.

La mateixa carpeta .devcontainer funciona al núvol amb GitHub Codespaces: en crear un Codespace, GitHub construeix automàticament l'entorn. Això afavoreix el canvi sense fricció entre local i núvol, reproductibilitat i incorporació ràpida de nous col·laboradors.

Bones pràctiques: considera les imatges base oficials devcontainers/, versiona la carpeta .devcontainer, utilitza postCreateCommand per automatitzar instal·lacions i combina devcontainer.json amb docker-compose.yml quan necessitis diversos serveis.

Alternativa: Docker sense Docker Desktop (motor nadiu a WSL2)

Si preferiu evitar Docker Desktop (per política d'empresa o elecció personal), podeu instal·lar el motor de Docker directament a la teva distro WSL2. Afegeix la clau GPG, el repositori oficial i els paquets (a Ubuntu):

Segueix aquestes ordres per afegir la clau i el repositori: # Clave oficial y repositorio
sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https:\/\/download.docker.com\/linux\/ubuntu\/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo «deb [arch=$(dpkg –print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https:\/\/download.docker.com\/linux\/ubuntu \n$(. \/etc\/os-release && echo «$VERSION_CO
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

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

Afegeix el teu usuari al grup docker per utilitzar el CLI sense sudo: sudo usermod -aG docker $USER. Tanca i reobre WSL. Comprova amb docker run hello-world. Per autoarrencar pots fer servir /etc/wsl.conf amb [boot] y command = service docker start, o systemd si ja està habilitat al teu WSL2 (en versions recents).

Xarxa i ports: des de Windows podràs accedir a contenidors publicats a localhost gràcies a WSL2. Si necessites exposar serveis de WSL2 cap a la teva xarxa local (per exemple, accedir des del mòbil), utilitza un port intermediari a Windows amb netsh i crea la regla de tallafocs corresponent. Un script de PowerShell típic obté la IP de WSL, configura portproxy i afegeix la regla; així evites repetir ordres després de reinicis.

Per què escollir aquesta ruta? Eviteu dependre de llicències o polítiques de Docker Desktop i controleu cada peça. Com a complement, pots desplegar Portainer per gestionar contenidors amb interfície web: crea un volum i aixeca el contenidor amb els ports 8000 i 9443; accedeix a https://localhost:9443 (accepta el certificat), crea l'usuari admin i gestiona el teu Docker amb clics.

Git, SSH i on clonar el codi

A WSL2 pots clonar amb Git al teu directori home de Linux i treballar amb VS Code. Aquesta sol ser l'opció més còmoda: millor rendiment i menys fricció. Si prefereixes clonar des d'un contenidor, hauràs de gestionar les credencials i les claus SSH dins del contenidor o muntar el teu ~/.ssh amb cura.

GUI per a Git? Eines com Sublime Merge o GitKraken poden funcionar en aquest escenari. GitKraken fins i tot pot obrir-se des de la terminal de WSL i mostrar-se al Windows, tenint accés als fitxers de WSL. Per a SSH amb GitLab o altres remots, configura les teves claus a WSL i comprova permisos i agents SSH abans de clonar per SSH.

Recordeu el consell de rendiment: evita /mnt/c per al teu codi si compilaràs o utilitzaràs eines Linux intensives. Usa \\wsl$ des de Windows per accedir a la mateixa carpeta quan ho necessitis.

Productivitat a la terminal: ZSH, Oh My Zsh, Powerlevel10k, Antigen, FZF i Tmux

Per a una terminal còmoda i potent, instal·la zsh amb sudo apt install zsh i canvia-la per defecte amb chsh -s $(which zsh). Després instal·la Oh My zsh amb el seu script oficial i dóna-li un aspecte i funcionalitat avançats.

El tema Powerlevel10k afegeix un prompt molt configurable amb integració Git i rendiment excel·lent. Instal·la-ho des del seu repo, col·loca-ho ZSH_THEME="powerlevel10k/powerlevel10k" en ~/.zshrc i segueix l'assistent per ajustar fonts i aspecte. Veuràs el teu estat de repo, branca i més d'una ullada.

Amb antigen gestionaràs plugins de ZSH de manera declarativa. Paquets útils: zsh-autosuggestions, un plugin per fzf, suport zsh-npm-scripts-autocomplete y zsh-z per saltar entre directoris. Afegeix NVM com a plugin o oficialment per canviar de versió de Node en calent.

Millora el flux amb bat y fd des d'apt (bat y fd-find a Ubuntu), i configura fzf per a cerques: Ctrl + R per a historial, Alt + C per a carpetes i Ctrl + T per a fitxers amb previsualització en color. Guanys de temps immediats al dia a dia.

Per multiplexar la terminal, utilitza Tmux (sudo apt install tmux) i el seu gestor de plugins TPM. Amb una configuració adequada tindràs temes, recuperació de sessions (resurrect/continuum), integració amb navegació tipus Vim i dreceres per dividir panells. Instal·la plugins amb Ctrl + Espacio i després I (i majúscula) dins de Tmux.

Bases de dades, GPU i aplicacions gràfiques

El vostre projecte pot necessitar una base de dades. Tens guies per MySQL, PostgreSQL, MongoDB, Redis, SQL Server o SQLite corrent dins de WSL o com a contenidors. Integra serveis a docker-compose.yml y fes que el teu Dev Container es connecti a ells sense complicacions.

Acceleració per GPU? WSL2 ofereix suport per workloads de machine learning usant la GPU, amb especial focus en NVIDIA i CUDA. A targetes AMD/Intel hi ha camins alternatius; revisa la documentació del teu fabricant per habilitar l'acceleració.

WSL2 permet executar aplicacions de GUI de Linux a Windows. Per a casos puntuals, pots obrir editors o eines gràfiques de Linux i es mostraran a finestres de Windows. Si veieu glitches, reinicieu WSL2 amb wsl --shutdown sol arreglar-ho.

Interoperabilitat i ordres útils

WSL i Windows s'entenen bé. Des de PowerShell, executa ordres Linux amb wsl, Per exemple: wsl ls -la. També podeu barrejar: wsl ls -la | findstr "git" o dir | wsl grep git per filtrar entre mons.

Des de Linux executa eines de Windows afegint .exe: notepad.exe .bashrc. També combinacions útils: ipconfig.exe | wsl grep IPv4 | wsl cut -d: -f2 per quedar-te amb la IP. Tot flueix entre tots dos sistemes.

Per muntar unitats externes a WSL2, seguiu la guia de muntatge de discos. Podràs accedir a USB o discos addicionals i treballar amb ells des de Linux.

Xarxa, ports i localhost

WSL2 mapeja automàticament els ports de l'entorn Linux a localhost a Windows. És a dir, si publiques un -p 3000:3000 a Docker, podràs entrar a http://localhost:3000 des del teu navegador a Windows sense fer res més.

Si vols exposar serveis de WSL2 a la LAN (un altre dispositiu a la teva xarxa), pots fer servir un script de PowerShell que obtingui la IP de WSL i invoqui netsh interface portproxy per forwardejar ports, a més de crear la regla de firewall amb New-NetFirewallRule. Això automatitza la publicació i evita repetir manualment els passos després de reinicis.

Problemes freqüents i com resoldre'ls

Contextos obsolets de Docker a WSL: si t'apareix un anomenat “wsl” heretat de previews antigues, esborra'l amb docker context rm wsl. Així evitaràs errors com open \\.\/pipe\/docker_wsl i et quedaràs amb el context per defecte.

On guarda Docker les dades sota WSL? Cerca \\wsl$\docker-desktop y \\wsl$\docker-desktop-data, o obre el teu distro i llança explorer.exe . per navegar. També tens \\wsl\<Distro>\mnt\wsl per veure emmagatzematge relacionat.

Glitxes de finestres GUI llançades des de WSL: de vegades les aplicacions basades en Electron mostren artefactes. Reinicia WSL2 amb wsl --shutdown i torna a intentar-ho. Microsoft va corregint aquests detalls amb el temps.

Sense systemd? En iteracions recents WSL2 pot activar systemd per defecte; si no és el teu cas, pots iniciar serveis amb /etc/wsl.conf i la secció [boot]. Comproveu la vostra versió i documentació si necessiteu serveis en background.

Vas actualitzar de WSL1 a WSL2 i Docker no coopera: de vegades queden restes de configuracions antigues com DOCKER_HOST=tcp://localhost:2375. Si veniu d'aquesta configuració, desinstal·leu Docker per complet a Windows i WSL (paquets, rutes i fitxers de configuració), i reinstal·la Docker Desktop amb backend WSL 2. Verifica amb wsl -l -v que existeixen docker-desktop y docker-desktop-data en versió 2.

Si utilitzes el motor nadiu a WSL2 sense Desktop i exposes el dimoni per TCP, recorda que sense TLS és insegur. Aquesta configuració és per a entorns de desenvolupament locals, no producció. Assegureu-vos de controlar bé la vostra xarxa i evita ports oberts innecessaris.

Consells finals i bones pràctiques

En projectes amb docker-compose.yml que assumeixen automatitzacions de Docker Desktop (muntatges i àlies de xarxa), ajusta rutes absolutes si veus volums amb ~ i afegeix extra_hosts amb host.docker.internal:host-gateway si el teu stack ho requereix. Petits canvis eviten sorpreses.

Per a VS Code, el combo WSL + Dev Containers + Docker et permet treballar dins del contenidor amb les mateixes extensions i configuració de l'editor. És una manera d'estandarditzar l'entorn entre membres de l'equip i reduir “la meva màquina funciona”.

Si prefereixes un enfocament sense Docker Desktop, el motor nadiu a WSL2 ofereix control granular i, amb Portainer, una interfície de gestió lleugera. Les dues rutes són vàlides i dependran de les teves necessitats, llicències i polítiques internes.

Disposeu d'un mapa complet: instal·lar i configurar WSL2, triar entre Docker Desktop o motor nadiu, treballar amb Dev Containers i VS Code, fer servir bases de dades i GPU, i elevar la teva productivitat amb una terminal afinada i Tmux. La clau és combinar aquestes peces segons el teu projecte i equip per aconseguir un entorn reproduïble, ràpid i còmode al dia a dia.