Entorn de desenvolupament PHP amb Laravel Sail i Docker a Windows 11

el dia


Per fer servir aquest entorn de desenvolupament, hem d'instal·lar Docker Desktop i a la web de Docker se'ns diu un dels requisits és tenir WSL a Windows.

1. WSL 2 (Windows Subsystem Linux)

Les instruccions per instal·lar WSL les podem trobar a microsoft.com:

Obrir el terminal PowerShell amb permisos d'administrador i executar wsl --install:

PS C:\Windows\system32> wsl --install
Downloading: Windows Subsystem for Linux 2.4.13
Installing: Windows Subsystem for Linux 2.4.13
Windows Subsystem for Linux 2.4.13 has been installed.
Installing Windows optional component: VirtualMachinePlatform

Deployment Image Servicing and Management tool
Version: 10.0.26100.1150

Image Version: 10.0.26100.3624

Enabling feature(s)
[==========================100.0%==========================]
The operation completed successfully.
The requested operation is successful. Changes will not be effective until the system is rebooted.
The requested operation is successful. Changes will not be effective until the system is rebooted.

2. Docker Desktop

Descarregar l'instal·lador de Docker Desktop des de la seva web i instal·lar, marcant la opció:

[x] Use WSL 2 instead of Hyper-V (recommended)

Un cop instal·lat i reiniciat el sistema, ja podem veure que tenim Docker instal·lat amb la comanda docker:

$ docker
Usage:  docker [OPTIONS] COMMAND

A self-sufficient runtime for containers

Common Commands:
run         Create and run a new container from an image
exec        Execute a command in a running container
ps          List containers
. . .

Tant un procés com l'altre requerirà reiniciar el sistema.

3. Ubuntu

Descarreguem des de la botiga de Microsoft del PC Windows una aplicació Ubuntu, en el nostre cas és un Ubuntu 24.04.1 LTS. Quan acaba la descarrega obrim aquest programa, cosa que obre una finestra amb un terminal que procedeix a la instal·lació. La configuració serà:

Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username: entoniperez
New password: secret
Retype new password: secret
passwd: password updated successfully
Installation successful!
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

Welcome to Ubuntu 24.04.1 LTS (GNU/Linux 5.15.167.4-microsoft-standard-WSL2 x86_64)

* Documentation:  https://help.ubuntu.com
* Management:     https://landscape.canonical.com
* Support:        https://ubuntu.com/pro

System information as of Sat Apr  5 14:36:34 CEST 2025

System load:  0.01                Processes:             71
Usage of /:   0.1% of 1006.85GB   Users logged in:       0
Memory usage: 4%                  IPv4 address for eth0: 172.24.53.214
Swap usage:   0%

This message is shown once a day. To disable it please create the
/home/entoniperez/.hushlogin file.

Això, a més, crea la carpeta \Ubuntu-24.04. La ruta completa al nostre ordinador és \\wsl.localhost\Ubuntu-24.04. I efectivament, les comandes Linux funcionen:

entoniperez@33956696W:~$ sudo apt update
[sudo] password for entoniperez:
Hit:1 http://archive.ubuntu.com/ubuntu noble InRelease
Get:2 http://security.ubuntu.com/ubuntu noble-security InRelease [126 kB]
Get:3 http://archive.ubuntu.com/ubuntu noble-updates InRelease [126 kB]
Get:4 http://archive.ubuntu.com/ubuntu noble-backports InRelease [126 kB]
...

Ara indiquem a WSL que treballi per defecte amb la distribució Linux que hem instal·lat. Obrim un terminal i executem:

$ wsl -s Ubuntu-24.04
The operation completed successfully.

Si ara executem wsl -l -v veiem que ara ja treballa sobre aquest sistema:

$ wsl -l -v
NAME              STATE           VERSION
* Ubuntu-24.04      Running         2
docker-desktop    Running         2

4. Laravel Sail

Obrim el Terminal de Windows (cercar Terminal al menú d'Inici o amb la icona de cercar de la barra de tasques). Aquest terminal permet afegir una pestanya clicant al símbol +, que mostra un desplegable on apareix Ubuntu-24.04.

Això ens permet executar les comandes a la distribució Linux que tenim instal·lada. Primer crearem un directory on allotjarem tots els projectes. Per això fem mkdir projects i ens hi movem dins amb cd projects.

Tot seguit hem d'engegar Docker Desktop: simplement obrim l'aplicació a Windows. Ara, dins de projects executem:

$ curl -s https://laravel.build/laravel-test | bash

Això crea tot l'scaffolding del projecte laravel. Un cop creat podem anar a aquest directori i veure totes les carpetes de Laravel:

$ cd laravel-test

Ara hem de crear els contenidors amb la comanda ./vendor/bin/sail up. Cap al final del procés que engega aquesta instrucció, veiem:

laravel.test-1  |    INFO  Server running on [http://0.0.0.0:80].
laravel.test-1  |
laravel.test-1  |   Press Ctrl+C to stop the server

Provem aquesta url:port (que és el mateix que anar a 127.0.0.1 o a localhost) i veiem una pàgina d'error de Laravel amb un problema amb la base de dades. És normal ja que no hem executat les migracions.

Aturem Sail amb CTRL+C al terminal Ubuntu i el tornem a engegar amb ./vendor/bin/sail up -d que aixeca el servei i el desconnecta (detached mode) del terminal. Ara podem executar la comanda de migracions: ./vendor/bin/sail artisan migrate:

$ ./vendor/bin/sail artisan migrate

INFO  Preparing database.

Creating migration table .................................. 24.68ms DONE

INFO  Running migrations.

0001_01_01_000000_create_users_table ...................... 99.08ms DONE
0001_01_01_000001_create_cache_table ...................... 31.83ms DONE
0001_01_01_000002_create_jobs_table ....................... 89.33ms DONE

Ara sí, al navegador no ens dona cap error. Per comprovar que tot funciona, editem la vista welcome.blade.php i recarreguem la pàgina al navegador. Funciona!

5. Base de dades

Per connectar a la base de dades del projecte amb un client (com pot ser DBeaver), ens instal·lem aquest client de base de dades i configurem una nova connexió amb les credencials que hi ha a l'arxiu .env. Ens surt un avís de DBeaver dient que ha de descarregar uns drivers. Ho acceptem i un cop creada la connexió ens hi connectem, cosa que funciona. Amb això ja hem pogut crear un usuari des del terminal amb Tinker:

$ ./vendor/bin/sail artisan tinker
Psy Shell v0.12.8 (PHP 8.4.5 — cli) by Justin Hileman
> User::create(["name"=> "larainfo","email"=>"larainfo@gmail.com","password"=>bcrypt("123456")]);
[!] Aliasing 'User' to 'App\Models\User' for this Tinker session.
= App\Models\User {#5223
    name: "larainfo",
    email: "larainfo@gmail.com",
    #password: "$2y$12$WztEJau2VJrI0gvHU9gzJuyyMRuNq2UsEaUay6eM97pzIXbmj.3cC",
    updated_at: "2025-04-05 20:06:43",
    created_at: "2025-04-05 20:06:43",
    id: 1,
}

> exit status 130

6. Visual Studio Code

Al terminal d'Ubuntu obrim el projecte amb VS Code amb la comanda code .. La primera vegada que ho fem es fa aquesta instal·lació:

$ code .
Installing VS Code Server for Linux x64 (4437686ffebaf200fa4a6e6e67f735f3edf24ada)
Downloading: 100%
Unpacking: 100%
Unpacked 2067 files and folders to /home/entoniperez/.vscode-server/bin/4437686ffebaf200fa4a6e6e67f735f3edf24ada.
Looking for compatibility check script at /home/entoniperez/.vscode-server/bin/4437686ffebaf200fa4a6e6e67f735f3edf24ada/bin/helpers/check-requirements.sh
Running compatibility check script
Compatibility check successful (0)

Entenem que això s'instal·la al servidor Ubuntu WSL: Ubuntu 24.04 a jutjar pel títol de la finestra de l'editor. Abans hem instal·lat l'extensió Remote Development al VS Code de l'ordinador amfitrió, però no està clar si és necessari o no. En tot cas, funciona.

Per obri el projecte amb l'editor de codi (VS Code) i que aquest reconegui les classes, etc. hem d'obrir el projecte des de dins del contenidor. Per això creem el directori .devcontainer i a dins hi creem l'arxiu devcontainer.json amb aquest contingut:

{
  "name": "Laravel Sail Dev Container",
  "dockerComposeFile": ["../docker-compose.yml"],
  "service": "laravel.test",
  "workspaceFolder": "/var/www/html",

  "customizations": {
    "vscode": {
      "settings": {
        "terminal.integrated.defaultProfile.linux": "bash",
        "intelephense.environment.includePaths": [
          "/var/www/html/app",
          "/var/www/html/vendor"
        ]
      },
      "extensions": [
        // PHP & Laravel
        "bmewburn.vscode-intelephense-client",
        "amiralizadeh9480.laravel-extra-intellisense",
        "onecentlin.laravel-blade",
        "onecentlin.laravel5-snippets",
        "ryannaddy.laravel-artisan",
        "mehedidracula.php-namespace-resolver",
        // Debug
        "felixfbecker.php-debug",
        "xdebug.php-pack",
        // Other utils
        "esbenp.prettier-vscode",
        "formulahendry.auto-close-tag"
      ]
    }
  }
}

Llavors, un cop obert amb code . farem Ctrl+Shift+P i escriurem Dev Containers: Reopen Folder in Container. Ara ja podem veure les classes citades passant el ratolí per sobre. Tot i que encara no hi podem accedir amb Alt+Click. Caldrà investigar...

7. GitKraken

Per fer servir aquest client de Git, haurem d'instal·lar-lo des del terminal d'Ubuntu, com una aplicació de Linux. Seguim aquestes instruccions que indica GitKraken. Bàsicament hem fet

$ wget https://release.gitkraken.com/linux/gitkraken-amd64.deb
$ sudo apt install ./gitkraken-amd64.deb
$ sudo apt --fix-broken install
$ gitkraken --disable-gpu

La última comanda obre GitKraken Desktop des de WSL com una aplicació de Linux/Ubuntu, deshabilitant l'ús de la targeta gràfica (evitant que ens vegi la pantalla negra). Allà configurem els comptes de GitLab i GitHub que tenim. Quan des de GitLab i GitHub ens demana permisos, en acceptar genera uns tokens. Els copiem i els enganxem a l'input que es mostra, i llavors ja tenim aquests serveis connectats. Amb això hem pogut clonar sense problemes un projecte allotjat a GitLab.

X. Laravel Sail | Ús habitual

  1. Obrir Docker Desktop.

  2. Obrir el terminal i en una nova pestanya, clicar la opció Ubuntu 24.04.1 LTS que es mostra.

  3. Anar a cd projects/nom-del-projecte.

  4. Executar ./vendor/bin/sail up -d per arrencar els contenidors en mode detached.

  5. Accedir a localhost des del navegador.

  6. ./vendor/bin/sail stop atura els contenidors en mode detached o normal.

  7. Les comandes que típicament es fan amb php artisan command ara cal fer-les amb ./vendor/bin/sail artisan. Igualment per a Node o NPM, com per exemple ./vendor/bin/sail npm -v o ./vendor/bin/sail php -v.

  8. Per crear un àlies de comanda, editem el fitxer .bashrc amb nano .bashrc i afegim aquesta línia:

    alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

    Ara podrem fer directament sail up -d o sail npm -v.

Comentaris

Publica un comentari a l'entrada