Desenvolupant Laravel amb Docker, mitjançant Sail

[actualitzat el divendres, 24 d'octubre de 2025]

Per fer servir Laravel Sail en un projecte que hem clonat a l'entorn WSL, però que no tenia Sail com a dependència per defecte (una versió de Laravel 9 o inferior), obrim el terminal (amb permisos d'administrador) i entrem al nostre directori de projectes. Allà executem una comanda per executar composer dins de Docker (es crea un contenidor temporal només per a això) i instal·lem composer:

$ docker run --rm \
  -v $(pwd):/app \
  -w /app \
  laravelsail/php82-composer:latest \
  composer require laravel/sail --dev

Després hem de copiar l'arxiu d'entorn (el configurarem segons el projecte):

$ cp .env.example .env

Tot seguit afegim el paquet Sail (tenir en compte que la versió de PHP pot variar) i l'instal·lem:

$ docker run --rm \
  -v $(pwd):/app \
  -w /app \
  laravelsail/php82-composer:latest \
  php artisan sail:install

En cas que el projecte clonat ja porti Sail

Aixequem els contenidors amb Sail:

sail up -d

Generem la clau:

$ sail artisan key:generate

Creem l'enllaç simbòlic (el projecte clonat el tenia) i netejem la caché:

$ sail artisan storage:link
sail artisan config:clear
sail artisan cache:clear
sail artisan view:clear

Per configurar la base de dades, editem l'arxiu .env:

DB_DATABASE=db_name
DB_USERNAME=sail
DB_PASSWORD=secret
FORWARD_DB_PORT=3306 # important si volem controlar el port exposat

Després executem les migracions amb la comanda usual: $ sail artisan migrate. Si hem d'importar un arxiu .sql d'una exportació que haguem fet, executarem

cat database/verticalpine.sql | docker exec -i verticalpine-mysql-1 mysql -usail -p verticalpine

des de dins del projecte i amb Sail engegat.

Amb aquests passos, el projecte clonat funciona. 

I si el projecte ja incorpora Sail?

Una altra possibilitat és que estiguem clonant un projecte que ja incorpora Sail com a dependència (una versió de Laravel 10 o superior). En aquest cas executarem:

$ docker run --rm \
    -u "$(id -u):$(id -g)" \
    -v "$(pwd)":/var/www/html \
    -w /var/www/html \
    laravelsail/php83-composer:latest \
    composer install --ignore-platform-reqs

Fixem-nos en la part --ignore-platform-reqs, que pot ser molt útil en el cas (com és usual si volem treballar amb Docker) que no tinguem instal·lat res —versió de PHP i les seves extensions, npm, nginx, etc.— al nostre ordinador.

Ara ja tenim laravel/sail a la carpeta /vendor (perquè estava al composer.json), però això només vol dir que la dependència està instal·lada, no que el projecte estigui configurat per utilitzar-la. Per fer funcionar Sail haurem d'instal·lar-ho amb composer, cosa que no podem fer per què no tenim composer instal·lat al sistema, només funcionarà dins el contenidor, que no arrencarà sense Sail. Sembla un carreró sense sortida però, novament (com abans), farem servir Docker per crear un contenidor temporal que instal·li Sail. La comanda a executar és:

docker run --rm \
    -u "$(id -u):$(id -g)" \
    -v "$(pwd)":/var/www/html \
    -w /var/www/html \
    laravelsail/php83-composer:latest \
    php artisan sail:install

Ara ja podem aixecar el projecte amb ./vendor/bin sail up -d o bé sail up -d si hem creat un àlies.

Ara ja sabem un mica com funciona Docker (però només una mica).