Zrychlení Docker devcontaineru na Windows přes WSL2 [Wiki]

Tato stránka je pouze pro čtení. Můžete si pouze prohlédnout zdrojový kód, ale ne ho měnit. Zeptejte se správce, pokud si myslíte, že něco není v pořádku.
====== Zrychlení Docker devcontaineru na Windows přes WSL2 ======

//Vytvořeno: **4.7.2026** | Aktualizováno: **~~LASTMOD~~**//

[[https://docs.docker.com/desktop/features/wsl/|Docker Desktop s WSL 2 backendem]] umožňuje na Windows provozovat Linux kontejnery nad WSL2. Pokud je ale projekt uložený na Windows disku a do [[https://code.visualstudio.com/docs/devcontainers/containers|Dev Containers]] se připojuje přes bind mount, mohou být diskové operace v kontejneru extrémně pomalé. Tento návod popisuje ověřený postup z [[https://opencode.e-nosek.cz/L2hvbWUvYWl3b3JrL3NjcmF0Y2g/session/ses_0d863da33ffeZIBQ4rhReC2RYh|pracovní OpenCode konverzace]]: přesunout workspace z Windows filesystemu do WSL2 Ubuntu filesystemu a teprve nad ním spustit Cursor/devcontainer.

===== Cíl =====

Původní stav:

<code text>
Windows filesystem:
C:\cursor-ai

Docker kontejner:
/home/ubuntu  <- bind mount z C:\cursor-ai
</code>

To bývá velmi pomalé, protože kontejner při práci se soubory sahá přes překladovou vrstvu Windows -> Linux.

Cílový stav:

<code text>
WSL2 Ubuntu filesystem:
/home/panhe/cursor-ai

Docker kontejner:
/home/ubuntu  <- bind mount z /home/panhe/cursor-ai
</code>

Data zůstávají mimo kontejner, přežijí rebuild kontejneru a zároveň se s nimi pracuje přes rychlý Linux filesystem.

===== Architektura =====

Po migraci jsou na Windows počítači dvě různé Linux vrstvy:

<code text>
Windows
├─ WSL2 Ubuntu
│  └─ /home/panhe/cursor-ai
│     = fyzické místo, kde leží projektová data
│
└─ Docker Desktop
   └─ Docker devcontainer Ubuntu
      └─ /home/ubuntu
         = vývojové prostředí, kam se data z WSL bind-mountují
</code>

WSL Ubuntu není Docker kontejner. Je to Linux distribuce běžící přes WSL2.

Docker kontejner je samostatné prostředí, které používá Docker Desktop. WSL Ubuntu slouží hlavně jako rychlý Linux filesystem a jako místo, odkud Cursor/Dev Containers spouští Docker příkazy. Docker kontejner je skutečné vývojové prostředí podle ''Dockerfile''.

===== Proč nestačí Cursor připojený do kontejneru =====

Pokud je v ''devcontainer.json'' nastavený bind mount:

<code json>
"mounts": [
  "source=${localWorkspaceFolder},target=/home/ubuntu,type=bind"
]
</code>

záleží na tom, odkud Cursor otevřel projekt.

Pokud Cursor otevře projekt z Windows cesty:

<code text>
C:\cursor-ai
</code>

mountuje se do kontejneru Windows filesystem.

Pokud Cursor otevře projekt přes WSL cestu:

<code text>
/home/panhe/cursor-ai
</code>

mountuje se do kontejneru WSL/Linux filesystem.

V Cursoru může prostředí vypadat stejně, protože v obou případech skončíš v kontejneru ve složce ''/home/ubuntu''. Rozdíl je ve zdroji mountu.

===== Co není potřeba měnit =====

V tomto scénáři není potřeba měnit ''Dockerfile''.

Také není nutné měnit ''devcontainer.json'', pokud se má dál mountovat celý obsah workspace do ''/home/ubuntu''.

Příklad původního nastavení může zůstat:

<code json>
{
  "name": "ai",
  "build": {
    "dockerfile": "Dockerfile"
  },
  "runArgs": [
    "--name=ai",
    "--cap-add=SYS_ADMIN",
    "--shm-size=2gb"
  ],
  "workspaceFolder": "/home/ubuntu",
  "mounts": [
    "source=${localWorkspaceFolder},target=/home/ubuntu,type=bind"
  ],
  "remoteUser": "ubuntu",
  "updateRemoteUserUID": true
}
</code>

Klíčová změna není v těchto souborech. Klíčová změna je v tom, že Cursor otevře projekt ze WSL filesystemu, ne z ''C:\''.

===== Postup =====

==== Krok 1: Zkontroluj WSL distribuce ====

Ve Windows otevři PowerShell a spusť:

<code powershell>
wsl -l -v
</code>

Můžeš vidět například:

<code text>
  NAME                   STATE           VERSION
* docker-desktop-data    Running         2
  docker-desktop         Running         2
</code>

To znamená, že zatím existují jen interní WSL distribuce Docker Desktopu:

<code text>
docker-desktop
docker-desktop-data
</code>

Tyto distribuce nejsou určené pro pracovní data. Nedávej do nich projekt a nepoužívej je jako pracovní Ubuntu.

==== Krok 2: Nainstaluj běžné Ubuntu do WSL2 ====

Pokud v seznamu není běžná distribuce, například ''Ubuntu-24.04'', nainstaluj ji podle [[https://learn.microsoft.com/en-us/windows/wsl/install|dokumentace Microsoft WSL]]:

<code powershell>
wsl --install -d Ubuntu-24.04
</code>

Tento příkaz nevytváří Docker kontejner. Vytváří běžnou WSL2 Ubuntu distribuci, kde bude Linux filesystem:

<code text>
/home/panhe/...
</code>

Po instalaci budeš vyzván k vytvoření Linux uživatele. V reálném příkladu byl uživatel:

<code text>
panhe
</code>

==== Krok 3: Nastav Ubuntu jako defaultní WSL distribuci ====

Pokud je defaultní distribuce ''docker-desktop-data'', Cursor se může pokusit připojit právě do ní. To vede k chybám typu:

<code text>
Resolving wsl remote authority 'wsl+docker-desktop-data'
getpwuid(0) failed
execvpe(bash) failed: No such file or directory
</code>

To znamená, že Cursor zkouší použít interní Docker distribuci, ne pracovní Ubuntu.

Nastav správný default:

<code powershell>
wsl --set-default Ubuntu-24.04
</code>

Ověř:

<code powershell>
wsl -l -v
</code>

Správně má být hvězdička u ''Ubuntu-24.04'':

<code text>
  NAME                   STATE           VERSION
* Ubuntu-24.04           Running         2
  docker-desktop         Running         2
  docker-desktop-data    Running         2
</code>

==== Krok 4: Zkopíruj data z Windows do WSL ====

Původní složka byla:

<code text>
C:\cursor-ai
</code>

Ve WSL je Windows disk ''C:'' dostupný jako:

<code text>
/mnt/c
</code>

Takže původní složka je ve WSL vidět jako:

<code text>
/mnt/c/cursor-ai
</code>

Spusť Ubuntu WSL:

<code powershell>
wsl -d Ubuntu-24.04
</code>

Ve WSL vytvoř cílovou složku a zkopíruj obsah:

<code bash>
mkdir -p ~/cursor-ai
sudo apt update
sudo apt install -y rsync
rsync -a --info=progress2 /mnt/c/cursor-ai/ ~/cursor-ai/
</code>

Pozor na lomítko na konci:

<code text>
/mnt/c/cursor-ai/
</code>

To znamená „zkopíruj obsah složky“, ne složku samotnou.

Po kopírování ověř:

<code bash>
cd /home/panhe/cursor-ai
pwd
ls
ls .devcontainer
git status
</code>

Správný ''pwd'' výstup:

<code text>
/home/panhe/cursor-ai
</code>

Špatný výstup by byl:

<code text>
/mnt/c/cursor-ai
</code>

==== Krok 5: Zapni Docker Desktop WSL integration ====

Když se Cursor připojí do WSL a pokusí se otevřít devcontainer, může se objevit chyba:

<code text>
Failed to reopen folder in container: Error running docker info.
The command 'docker' could not be found in this WSL 2 distro.
We recommend to activate the WSL integration in Docker Desktop settings.
</code>

To neznamená, že je potřeba instalovat nový Docker engine do WSL.

Standardní řešení na Windows je použít Docker Desktop a zapnout jeho integraci do WSL distribuce. Postup je v [[https://docs.docker.com/desktop/features/wsl/|Docker Desktop WSL 2 dokumentaci]].

Ve Windows otevři Docker Desktop:

<code text>
Settings -> Resources -> WSL Integration
</code>

Zapni:

<code text>
Enable integration with my default WSL distro
</code>

Případně explicitně zapni:

<code text>
Ubuntu-24.04
</code>

Pak klikni:

<code text>
Apply & Restart
</code>

Ověř ve WSL:

<code bash>
docker version
docker info
docker ps -a
</code>

Pokud příkaz ''docker'' funguje, WSL Ubuntu umí komunikovat s Docker Desktopem.

==== Krok 5.1: Zajisti funkčnost po restartu Windows ====

Po restartu Windows může být WSL distribuce ve stavu:

<code text>
Stopped
</code>

To samo o sobě není chyba. WSL distribuce se umí spustit automaticky ve chvíli, kdy ji něco potřebuje.

Pro praktickou práci ale může být pohodlnější zajistit, aby po přihlášení běžel Docker Desktop i WSL Ubuntu.

=== Automatický start Docker Desktopu ===

V Docker Desktopu otevři:

<code text>
Settings -> General
</code>

Zapni:

<code text>
Start Docker Desktop when you sign in
</code>

Potom zkontroluj:

<code text>
Settings -> Resources -> WSL Integration
</code>

Musí být zapnuté:

<code text>
Enable integration with my default WSL distro
</code>

a/nebo explicitně:

<code text>
Ubuntu-24.04
</code>

=== Volitelné držení WSL Ubuntu přes sleep infinity ===

Pokud má WSL Ubuntu po startu Windows zůstat běžet pořád, lze použít Windows Task Scheduler.

Tento krok není povinný, ale je praktický, pokud má být prostředí po restartu předvídatelné a hned připravené pro Cursor.

Ve Windows otevři:

<code text>
Task Scheduler
</code>

Vytvoř novou úlohu:

<code text>
Create Basic Task
</code>

Název například:

<code text>
Start WSL Ubuntu
</code>

Trigger:

<code text>
When I log on
</code>

Action:

<code text>
Start a program
</code>

Program:

<code text>
wsl.exe
</code>

Arguments:

<code text>
-d Ubuntu-24.04 --exec bash -lc "sleep infinity"
</code>

Tím se po přihlášení spustí Ubuntu WSL a uvnitř poběží nekonečný proces ''sleep infinity''. Díky tomu distribuce zůstane ve stavu ''Running''.

Co je dobré vědět:

  * WSL Ubuntu po startu Windows běží a Cursor se do něj může rychleji připojit.
  * WSL bude trvale zabírat část RAM.
  * Task Scheduler úloha bude pořád ve stavu ''Running''.
  * WSL poběží, ale Docker Desktop stejně musí být také nastartovaný.

''sleep infinity'' nenahrazuje Docker Desktop autostart ani WSL Integration. Jen drží WSL distribuci živou.

=== Ověření po restartu ===

Po restartu Windows ověř v PowerShellu:

<code powershell>
wsl -l -v
</code>

Očekávané je, že ''Ubuntu-24.04'' může být ''Running'', pokud používáš ''sleep infinity'', nebo ''Stopped'', pokud keepalive nepoužíváš.

Při použití ''sleep infinity'' chceš vidět:

<code text>
Ubuntu-24.04    Running    2
</code>

Potom ověř Docker dostupný z WSL:

<code powershell>
wsl -d Ubuntu-24.04 -- docker ps
</code>

Pokud tento příkaz projde, WSL i Docker Desktop integrace fungují.

=== Jak WSL ručně zastavit ===

Pokud budeš chtít WSL Ubuntu ručně zastavit, spusť v PowerShellu:

<code powershell>
wsl --terminate Ubuntu-24.04
</code>

Nebo zastav celé WSL prostředí:

<code powershell>
wsl --shutdown
</code>

Pokud je zapnutá Task Scheduler úloha se ''sleep infinity'', WSL se znovu spustí při dalším přihlášení do Windows.

==== Krok 6: Otevři Cursor správně přes WSL ====

V Cursoru nepoužívej otevření složky přes Windows cestu:

<code text>
C:\cursor-ai
</code>

Ani jako primární cestu nepoužívej síťovou Windows cestu:

<code text>
\\wsl.localhost\Ubuntu-24.04\home\panhe\cursor-ai
</code>

Tato cesta je užitečná pro Windows Explorer, ale pro vývoj je lepší použít Cursor Remote WSL.

V Cursoru spusť Command Palette:

<code text>
Ctrl + Shift + P
</code>

Použij:

<code text>
Remote-WSL: New WSL Window
</code>

nebo:

<code text>
WSL: Connect to WSL
</code>

Pokud je k dispozici více distribucí, vyber explicitně:

<code text>
Ubuntu-24.04
</code>

V novém WSL okně Cursoru dej:

<code text>
File -> Open Folder
</code>

Zadej Linux cestu:

<code text>
/home/panhe/cursor-ai
</code>

Cursor najde:

<code text>
/home/panhe/cursor-ai/.devcontainer/devcontainer.json
</code>

==== Krok 7: Rebuild devcontaineru ====

V Cursoru spusť:

<code text>
Dev Containers: Rebuild and Reopen in Container
</code>

Pokud existuje starý kontejner se stejným jménem, například ''ai'', může nastat konflikt kvůli:

<code json>
"--name=ai"
</code>

V tom případě je možné starý kontejner odstranit, ale pouze pokud je jasné, že důležitá data jsou v bind mountu a ne jen uvnitř kontejneru.

Příklad:

<code powershell>
docker stop ai
docker rm ai
</code>

Potom znovu spusť rebuild devcontaineru.

==== Krok 8: Ověř, že nový kontejner používá WSL filesystem ====

Nejspolehlivější kontrola je přes ''docker inspect''.

Spusť ji ve WSL Ubuntu, ne uvnitř kontejneru:

<code bash>
docker inspect ai --format '{{range .Mounts}}{{println .Type .Source "->" .Destination}}{{end}}'
</code>

Správný výstup v reálném příkladu byl:

<code text>
bind /home/panhe/cursor-ai -> /workspaces/cursor-ai
bind /home/panhe/cursor-ai -> /home/ubuntu
</code>

To je v pořádku. Znamená to, že zdroj dat je:

<code text>
/home/panhe/cursor-ai
</code>

a ne:

<code text>
C:\cursor-ai
</code>

ani:

<code text>
/run/desktop/mnt/host/c/cursor-ai
</code>

Pokud je vidět ''/home/panhe/cursor-ai -> /home/ubuntu'', migrace se povedla.

===== Proč jsou tam dva mounty =====

Výstup může obsahovat dva bind mounty:

<code text>
bind /home/panhe/cursor-ai -> /workspaces/cursor-ai
bind /home/panhe/cursor-ai -> /home/ubuntu
</code>

To znamená, že stejný WSL adresář je v kontejneru dostupný na dvou místech.

Jeden mount může vytvořit Dev Containers automaticky:

<code text>
/workspaces/cursor-ai
</code>

Druhý odpovídá vlastnímu nastavení v ''devcontainer.json'':

<code text>
/home/ubuntu
</code>

Pokud se pracuje podle ''workspaceFolder'' v ''/home/ubuntu'', je hlavní tento mount:

<code text>
bind /home/panhe/cursor-ai -> /home/ubuntu
</code>

Není to problém, pokud všechno funguje.

===== Další ověření zevnitř kontejneru =====

V terminálu Cursoru uvnitř kontejneru spusť:

<code bash>
pwd
mount | grep /home/ubuntu
time git status
</code>

''pwd'' může ukázat:

<code text>
/home/ubuntu
</code>

To je správně. Rozdíl není v tom, jak cesta vypadá uvnitř kontejneru. Rozdíl je v tom, odkud je ''/home/ubuntu'' namountované.

===== Přístup k WSL souborům z Windows =====

Z Windows Exploreru lze otevřít:

<code text>
\\wsl.localhost\Ubuntu-24.04\home\panhe\cursor-ai
</code>

Tuto cestu lze použít pro občasné otevření, kopírování nebo kontrolu souborů z Windows.

Pro běžnou práci s projektem ale používej Cursor přes WSL a devcontainer. Nedoporučuje se dělat náročné operace jako Git, ''npm install'', ''composer install'' nebo indexaci přes Windows aplikace nad ''\\wsl.localhost''.

===== Časté chyby =====

==== Cursor se připojuje do docker-desktop-data ====

Příznak:

<code text>
Resolving wsl remote authority 'wsl+docker-desktop-data'
getpwuid(0) failed
execvpe(bash) failed: No such file or directory
</code>

Význam:

<code text>
Cursor se snaží použít interní Docker WSL distribuci místo Ubuntu-24.04.
</code>

Řešení:

<code powershell>
wsl --set-default Ubuntu-24.04
</code>

Potom znovu otevři WSL okno v Cursoru.

==== Ve WSL není příkaz docker ====

Příznak:

<code text>
The command 'docker' could not be found in this WSL 2 distro.
</code>

Význam:

<code text>
Docker Desktop není integrovaný do této WSL distribuce.
</code>

Řešení:

<code text>
Docker Desktop -> Settings -> Resources -> WSL Integration
</code>

Zapnout integraci pro default WSL distribuci nebo přímo pro ''Ubuntu-24.04''.

==== V docker inspect je pořád Windows cesta ====

Příznak:

<code text>
bind /run/desktop/mnt/host/c/cursor-ai -> /home/ubuntu
</code>

nebo:

<code text>
bind C:\cursor-ai -> /home/ubuntu
</code>

Význam:

<code text>
Projekt je pořád otevřený z Windows filesystemu.
</code>

Řešení:

Zavřít okno Cursoru a otevřít projekt z WSL Remote okna jako:

<code text>
/home/panhe/cursor-ai
</code>

ne jako:

<code text>
C:\cursor-ai
</code>

===== Finální kontrolní checklist =====

Ve Windows PowerShellu:

<code powershell>
wsl -l -v
</code>

Očekávané:

<code text>
* Ubuntu-24.04    ...    2
</code>

Pokud se používá Task Scheduler se ''sleep infinity'', po restartu Windows očekávej:

<code text>
Ubuntu-24.04    Running    2
</code>

Ve Windows PowerShellu ověř Docker dostupný z WSL:

<code powershell>
wsl -d Ubuntu-24.04 -- docker ps
</code>

Očekávané:

<code text>
docker příkaz projde bez chyby
</code>

Ve WSL:

<code bash>
pwd
</code>

Očekávané ve složce projektu:

<code text>
/home/panhe/cursor-ai
</code>

Ve WSL:

<code bash>
docker ps -a
</code>

Očekávané:

<code text>
docker příkaz funguje a jsou vidět kontejnery Docker Desktopu
</code>

Ve WSL:

<code bash>
docker inspect ai --format '{{range .Mounts}}{{println .Type .Source "->" .Destination}}{{end}}'
</code>

Očekávané:

<code text>
bind /home/panhe/cursor-ai -> /home/ubuntu
</code>

V kontejneru:

<code bash>
cd /home/ubuntu
time git status
</code>

Očekávané:

<code text>
git status je výrazně rychlejší než při práci nad C:\cursor-ai
</code>

===== Shrnutí =====

Funkční řešení není „připojit Cursor do kontejneru“ samo o sobě. Funkční řešení je otevřít projekt z WSL filesystemu a až potom spustit devcontainer.

Správný řetězec je:

<code text>
Windows
-> Cursor Remote WSL: Ubuntu-24.04
-> otevřená složka /home/panhe/cursor-ai
-> Dev Containers rebuild
-> kontejner ai
-> /home/ubuntu bind mount z /home/panhe/cursor-ai
</code>

Data zůstávají dostupná z Windows přes:

<code text>
\\wsl.localhost\Ubuntu-24.04\home\panhe\cursor-ai
</code>

a zároveň kontejner pracuje s rychlým Linux filesystemem místo pomalého Windows bind mountu.

===== Zdroje =====

  * [[https://opencode.e-nosek.cz/L2hvbWUvYWl3b3JrL3NjcmF0Y2g/session/ses_0d863da33ffeZIBQ4rhReC2RYh|Pracovní OpenCode konverzace k migraci Windows devcontaineru na WSL2 filesystem]]
  * [[https://docs.docker.com/desktop/features/wsl/|Docker Desktop – WSL 2 backend]]
  * [[https://learn.microsoft.com/en-us/windows/wsl/install|Microsoft – instalace WSL]]
  * [[https://code.visualstudio.com/docs/devcontainers/containers|Visual Studio Code Dev Containers]]