intranetBatoi

Desplegament Docker: desenvolupament i servidor

Esta és la recepta canònica per a agents i persones que preparen la intranet amb Docker. Separa tres rols: màquina de desenvolupament, màquina que construeix/publica la imatge i servidor que només l’executa.

Invariants

1. Màquina de desenvolupament

Requisits: repositori clonat, Docker Engine i Docker Compose. No assumes que .env local existeix ni el substituïsques si ja està configurat.

cp .env.docker .env
export WWWUSER="$(id -u)"
export WWWGROUP="$(id -g)"
docker compose config --quiet
docker compose up -d --build
docker compose exec -T --user sail laravel.test composer install
docker compose exec -T --user sail laravel.test npm install
docker compose exec -T --user sail laravel.test npm run production
docker compose exec -T --user sail laravel.test php artisan key:generate
docker compose exec -T --user sail laravel.test php artisan migrate
docker compose ps

WWWUSER i WWWGROUP s’han d’exportar en cada shell nova que invoque Compose. Alineen el contenidor sail amb l’usuari que posseeix el repositori muntat i eviten fitxers generats amb propietari incorrecte.

Dades de prova

Abans de migrar una màquina de desenvolupament, pregunta una sola vegada: «Vols instal·lar les dades i l’usuari de prova?». No pressuposes la resposta i no executes cap seed en les fases build o servidor.

No uses migrate:fresh --seed en una base existent: elimina totes les dades. Només és una verificació controlada en un entorn de prova descartable.

2. Construir i publicar des d’una màquina amb eines de desenvolupament

La imatge de producció es construeix amb docker/8.3/Dockerfile.prod. Inclou dependències PHP sense desenvolupament, npm install i npm run production.

export IMAGE_TAG_PROD="2026.11.06-<versio>"
export WWWUSER="$(id -u)"
export WWWGROUP="$(id -g)"
docker build \
  --build-arg WWWUSER="$WWWUSER" \
  --build-arg WWWGROUP="$WWWGROUP" \
  -f docker/8.3/Dockerfile.prod \
  -t "arturocandela/intranet:${IMAGE_TAG_PROD}" .
docker run --rm --entrypoint /bin/sh "arturocandela/intranet:${IMAGE_TAG_PROD}" -lc 'test -f public/build/manifest.json'

Usa etiquetes immutables i descriu exactament la destinació abans de publicar:

docker push "arturocandela/intranet:${IMAGE_TAG_PROD}"

No uses latest com a única referència per a una actualització manual o un rollback.

3. Servidor sense eines de desenvolupament

El servidor només necessita Docker Engine, Docker Compose, accés al registre d’imatges i un directori de desplegament amb estos fitxers:

<directori-desplegament>/
  docker-compose.prod.yml
  Caddyfile
  .env
  storage/

Mantín .env fora de la imatge i protegeix-lo. storage/ ha de persistir entre versions.

export IMAGE_TAG_PROD="2026.11.06-<versio>"
export WWWUSER="$(id -u)"
export WWWGROUP="$(id -g)"
docker compose -f docker-compose.prod.yml config --quiet
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs --tail=100 laravel.prod caddy

No cal clonar el repositori, instal·lar Composer ni instal·lar Node al servidor.

Ruta de storage actual

El docker-compose.prod.yml actual munta storage des de /var/www/html/intranetBatoi/storage, una ruta absoluta específica. Abans del primer desplegament, l’agent ha de comprovar que esta ruta existeix i és persistent. Si el servidor usa un altre directori, ha de parar i demanar autorització per a adaptar el compose; no ha d’inventar una ruta ni crear un muntatge diferent silenciosament.

Verificació i incidències

Després d’arrancar, comprova que Caddy servix el domini esperat i que els assets de public/build/ es carreguen. L’aplicació actual no publica /up: esta URL respon 404 i el healthcheck de laravel.prod ha de revisar-se abans d’exigir que el servei aparega saludable. Per a problemes amb Selenium/SAO, consulta selenium-sao-prod.md.

Si fallen permisos, compara id -u/id -g de l’host amb WWWUSER/WWWGROUP, revisa propietat de storage i bootstrap/cache, i mira els logs abans de canviar permisos recursivament. No borres volums ni dades per a “provar” una correcció.

Adaptadors d’agents