Herramientas de usuario

Herramientas del sitio


clase:daw:daw-proyecto:tema04

4. Build y despliegue en local

El objetivo del tema es gestionar el arranque y la parada de la aplicación de cada worktree con una sola orden, sin tener que recordar cómo se lanza cada pieza. Para ello se crea el script devops-desktop.sh con todas sus órdenes.

Lo que ya se sabe y aquí no se repite: lanzar un contenedor con docker run (Despliegue 3) y, como en la práctica siempre se usa, Docker Compose (Despliegue 5). Lo nuevo: devops-desktop.sh, el compose.yaml del proyecto y los puertos de cada worktree.

El script devops-desktop.sh

El proyecto tiene en la raíz un script de bash, devops-desktop.sh, con las órdenes de ./devops-desktop.sh del tema 1:

Orden Qué hace
./devops-desktop.sh deploy Compila y arranca la aplicación del worktree con sus datos de prueba
./devops-desktop.sh undeploy Para la aplicación. Los datos se quedan
./devops-desktop.sh status Dice si están arrancados los tres servidores
./devops-desktop.sh log Muestra el log del backend
./devops-desktop.sh delete-db Borra la base de datos del worktree

Operar la aplicación no necesita ninguna inteligencia, así que no es una skill. Igual que /do-git-flow, el script lo escribe el alumno con el agente a partir de lo que dice cada orden (abajo). Trabaja sobre la carpeta en la que está: cada worktree opera su aplicación. En Windows se ejecuta desde Git Bash (Despliegue 1).

Los tres servidores

La aplicación son tres servidores que devops-desktop.sh arranca y para juntos. Solo la base de datos va en Docker: el servidor y el cliente se ejecutan directamente en la máquina, que tiene instalados el JDK, Maven y Node.

Servidor Tecnología Se arranca con Puerto por defecto
Servidor (backend) Spring Boot java -jar 8080
Cliente (frontend) Angular npx ng serve 4200
Base de datos MariaDB en Docker docker compose up -d --wait 3306

Servidor: Spring Boot

El backend es una aplicación Spring Boot. Lleva dentro su servidor web, así que se compila a un JAR y se lanza con java, sin instalar nada más. Escucha en el 8080 y se conecta a la base de datos en el 3306:

spring.datasource.url=jdbc:mariadb://localhost:3306/tienda
spring.datasource.username=tienda
spring.datasource.password=tienda

Se compila en backend/ y se lanza el JAR:

mvn clean package
java -jar target/tienda-0.0.1-SNAPSHOT.jar

  • clean: borra target/ antes de compilar. Sin él se quedan en el JAR las clases de ficheros ya borrados o renombrados, y la aplicación hace cosas que el código ya no dice.
  • package pasa antes los tests unitarios y de arquitectura (tema 6), que no necesitan nada arrancado. Si falla uno, no hay JAR: no se arranca un backend roto.
  • El backend no se recarga solo: cada cambio en Java es compilar y volver a lanzar, que es lo que hace ./devops-desktop.sh deploy.

Cliente: Angular

El frontend es Angular. En desarrollo no se compila a mano: lo sirve el servidor de desarrollo de Angular en el 4200, que recarga el navegador al guardar un fichero. Se lanza en frontend/:

npx ng serve

El servidor de Angular hace además de proxy: todo lo que le llega a /api lo reenvía al backend. Así la aplicación de Angular siempre llama a /api, a su propio servidor, y nunca al backend directamente:

  • El código pide http.get('/api/clientes') y el navegador lo manda a http://localhost:4200/api/clientes.
  • ng serve ve que empieza por /api y reenvía la petición a http://localhost:8080/api/clientes.
  • La respuesta del backend vuelve al navegador por el mismo camino.

El código de Angular no sabe en qué puerto está el backend, y no hay problemas de CORS: para el navegador todo viene del 4200. El proxy se configura en un fichero:

{ "/api": { "target": "http://localhost:8080" } }

Se activa en angular.json, en serve → options: "proxyConfig": "proxy.conf.json".

Base de datos: MariaDB

La base de datos es MariaDB en un contenedor, con Docker Compose. El compose.yaml del proyecto solo la levanta a ella, en el 3306:

services:
  db:
    image: mariadb:11
    environment:
      MARIADB_DATABASE: tienda
      MARIADB_USER: tienda
      MARIADB_PASSWORD: tienda
      MARIADB_ROOT_PASSWORD: tienda
    ports:
      - "3306:3306"
    volumes:
      - ./tmp/db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 2s
      retries: 30

Se arranca en la raíz del worktree:

docker compose up -d --wait

  • ./tmp/db: los datos van en la carpeta tmp/db del worktree. Cada worktree tiene su base de datos, que sobrevive a parar el contenedor y desaparece con la carpeta. tmp/ va en el .gitignore.
  • healthcheck: --wait espera a que MariaDB acepte conexiones. Sin él, el backend arranca antes que la base de datos y muere.
  • El contenedor se llama como la carpeta del worktree, que lleva el nombre de la rama: tienda-wt-alta-clientes-12-db-1. Así docker compose en un worktree solo ve el suyo.
  • Las contraseñas en claro valen porque es la base de datos de desarrollo, que solo existe en el ordenador local.
En Linux, los ficheros de tmp/db son del usuario de MariaDB dentro del contenedor, no del alumno: rm -rf tmp/db da Permiso denegado y /do-git-flow issue-finish no puede borrar el worktree. Se borran desde un contenedor, que es lo que hace ./devops-desktop.sh delete-db. En Windows no pasa, pero el script es el mismo.

devops-desktop.sh

Veamos ahora cada uno de los comandos del devops-desktop.sh y después de ellos veremos los dos problemas que hay:

  • Segundo plano y log: cómo lanzar los servidores en segundo plano y cómo guardar el log.
  • Puertos: cómo indicar en qué puertos arrancan los tres servidores.

./devops-desktop.sh deploy

Compila y arranca la aplicación del worktree con sus datos de prueba. Vale para todo: la primera vez, después de cambiar el backend y al día siguiente.

Precondiciones

  1. Docker está arrancado. Si no: «Docker no está arrancado: ábrelo y vuelve a lanzar deploy»

Acciones

  1. Si el backend o el frontend ya están arrancados, los para como undeploy (sin tocar la base de datos): así deploy también vuelve a compilar.
  2. Crea tmp/db si no existe (si la crea Docker, es de root) y arranca la base de datos esperando a que esté lista (pista: --wait).
  3. Compila el backend desde cero y con sus tests (pista: mvn clean package). Si no compila o falla un test, para: «El backend no compila o falla un test: mira los errores de arriba».
  4. Arranca el backend en segundo plano con su log en tmp/back.log.
  5. Si no hay frontend/node_modules (un worktree recién creado no lo tiene), npm ci en frontend/. Arranca el frontend en segundo plano con su log en tmp/front.log.
  6. Espera a que respondan el backend (/api/hola) y el frontend, dos minutos como mucho. Si no: «El backend no arranca: ./devops-desktop.sh log» o «El frontend no arranca: mira tmp/front.log».
  7. Responde: «Aplicación en http://localhost:4200».

./devops-desktop.sh undeploy

Para todo lo que ha arrancado deploy. Los datos se quedan en tmp/db: el siguiente deploy la deja como estaba.

Precondiciones

  1. Docker está arrancado. Si no: «Docker no está arrancado: ábrelo y vuelve a lanzar undeploy»

Acciones

  1. Para lo que escucha en el puerto del frontend y en el del backend (pista: por puerto).
  2. Borra el contenedor de la base de datos (pista: docker compose down).
  3. Responde: «Aplicación parada. Los datos siguen en tmp/db».

./devops-desktop.sh log

Muestra el log del backend: es lo primero que se mira cuando algo no responde.

Precondiciones

  1. Existe tmp/back.log. Si no: «No hay log: la aplicación no se ha arrancado en este worktree»

Acciones

  1. Muestra las últimas 100 líneas (pista: tail sin -f, o el agente se queda esperando).

./devops-desktop.sh status

Dice si están arrancados los tres servidores.

Acciones

  1. Comprueba cada una y escribe una línea por servidor con ✓ o ✗:
    • Base de datos: su contenedor está healthy (pista: docker compose ps).
    • Backend: responde http://localhost:8080/api/hola.
    • Frontend: responde http://localhost:4200.
  2. Si están las tres: «Aplicación en http://localhost:4200».

./devops-desktop.sh delete-db

Borra la base de datos del worktree. El siguiente deploy la crea desde cero con las migraciones y los datos de prueba.

Precondiciones

  1. No existe el contenedor de la base de datos del worktree (pista: docker compose ps -a no da nada). Si no: «La base de datos está arrancada: ./devops-desktop.sh undeploy y vuelve a lanzar delete-db»

Acciones

  1. Vacía tmp/db desde un contenedor de la propia imagen (pista: docker compose run --rm con otro entrypoint), no con rm desde la máquina: en Linux daría Permiso denegado.
  2. Responde: «Base de datos borrada: el próximo deploy la crea con los datos de prueba».

Segundo plano y log

deploy tiene que terminar y dejar el backend y el frontend corriendo, con su salida en un fichero. Es igual en Linux y en Git Bash:

nohup java -jar backend/target/tienda-0.0.1-SNAPSHOT.jar > tmp/back.log 2>&1 &

  • &: lo deja en segundo plano y el script sigue.
  • nohup: sigue corriendo aunque se cierre la terminal.
  • > tmp/back.log 2>&1: la salida normal y la de errores, al log. El del frontend, a tmp/front.log.

Para pararlos no vale guardar el PID que da $!: npx ng serve lanza npm, que lanza ng serve, que lanza esbuild. Lo que se para es lo que escucha en el puerto, con todos sus hijos:

  • Linux: lsof -ti tcp:8080 -sTCP:LISTEN da el PID y se para con kill.
  • Windows (uname empieza por MINGW): netstat -ano lista los puertos; el PID es la última columna de la línea con :8080 y LISTENING. Se para con taskkill //PID <pid> //T //F. Con // y no /, porque Git Bash convierte /PID en una ruta de disco; //T para también los hijos.

Puertos

Con los puertos por defecto (3306, 8080 y 4200) solo puede haber una aplicación arrancada: dos worktrees a la vez chocan, y también choca con lo que ya use esos puertos en el ordenador (un MySQL instalado, otro Spring Boot abierto en IntelliJ). Por eso cada worktree tiene sus puertos en un fichero .env en su raíz, ignorado por git:

DB_PORT=33112
BACKEND_PORT=8112
FRONTEND_PORT=4212

Cada servidor necesita conocer su puerto, para escuchar en él, y el del servidor al que llama:

Servidor DB_PORT BACKEND_PORT FRONTEND_PORT
Base de datos ✓ (el suyo)
Backend ✓ (se conecta a ella) ✓ (el suyo)
Frontend ✓ (el proxy le reenvía /api) ✓ (el suyo)

:!: Solo Docker Compose lee el .env por su cuenta. A los demás se lo hace llegar alguien:

Quién ¿Lee el .env solo? Quién lo carga
Docker Compose ✓ Nadie: lee el de la carpeta en la que se lanza
Spring Boot ✗ devops-desktop.sh, con set -a; source .env
ng serve (el proxy) ✗ devops-desktop.sh, con set -a; source .env

Para usarlos, cada servidor tiene que poder recibir su puerto, con el de siempre por defecto. En cada uno se cambia la aplicación, para que el puerto no esté escrito a fuego, y la forma de arrancarlo, para pasarle el del .env. La base de datos solo necesita lo segundo.

Backend

Cambios en la app

El puerto propio y el de la base de datos pasan a ser variables con valor por defecto:

server.port=${PORT:8080}
spring.datasource.url=jdbc:mariadb://localhost:${DB_PORT:3306}/tienda

Cambios al arrancar

Spring Boot no lee el .env: los puertos se le pasan como argumentos, y devops-desktop.sh pone los del .env:

java -jar backend/target/tienda-0.0.1-SNAPSHOT.jar --PORT=$BACKEND_PORT --DB_PORT=$DB_PORT

  • --PORT=8112 da valor al PORT de application.properties y tapa su 8080. Igual --DB_PORT.

Frontend

Cambios en la app

El proxy tiene que apuntar al puerto del backend, así que pasa a ser JavaScript, que puede leer variables de entorno:

export default {
  '/api': { target: `http://localhost:${process.env.BACKEND_PORT ?? 8080}` },
};

Y se le dice a ng serve que lo use en frontend/angular.json (en la raíz del proyecto Angular, junto a package.json). En el bloque "serve", que es la configuración de ng serve, la línea de proxyConfig pasa de proxy.conf.json a proxy.conf.mjs; lo demás no cambia:

"serve": {
  "options": {
    "proxyConfig": "proxy.conf.mjs"
  }
}

Cambios al arrancar

El puerto propio va en --port. El del backend no se pasa: el proxy lo lee de la variable de entorno BACKEND_PORT, que devops-desktop.sh exporta al cargar el .env:

npx ng serve --port $FRONTEND_PORT

Base de datos

Cambios al arrancar

Compose lee solo el .env de la carpeta en la que se lanza, así que basta con usar la variable en compose.yaml:

    ports:
      - "${DB_PORT:-3306}:3306"

En devops-desktop.sh

  • Carga el .env si existe y exporta sus variables, o ng serve no verá BACKEND_PORT (pista: set -a antes de cargarlo).
  • Da a cada variable el puerto de siempre si el .env no la trae (pista: BACKEND_PORT=${BACKEND_PORT:-8080}). Sin eso, en la carpeta principal se lanzaría --PORT= vacío y el backend no arranca.
  • Usa esos puertos en todo: arrancar, parar, status y la URL que responde.
  • Los tests de Playwright también leen el .env (tema 6).

Sin .env todo vale lo de siempre: es lo que pasa en la carpeta principal.

/do-git-flow y la aplicación

Dos comandos de la skill /do-git-flow del tema 3 hacen algo más:

  • issue-start: busca puertos libres a partir de una base más el número del issue (33100+N, 8100+N, 4200+N: con el #12 salen 33112, 8112 y 4212), escribe el .env del worktree y termina diciendo cómo arrancar. No arranca la aplicación.
  • issue-finish: ejecuta ./devops-desktop.sh undeploy y ./devops-desktop.sh delete-db en el worktree antes de borrarlo. Sin el delete-db, en Linux no puede borrar tmp/db.

Ejercicios

Con OpenCode y con /do-git-flow para todo lo de git, en el repositorio del tema 1. Cada ejercicio sigue donde lo dejó el anterior.

Ejercicio 1

Crear el devops-desktop.sh del proyecto, orden a orden. Cada orden se le pide al agente en una conversación nueva (/new) pasándole su apartado, se lee lo que escribe y se prueba antes de pedir la siguiente.

  • Crea el issue «Script devops-desktop.sh» con /do-git-flow issue-create e inícialo con /do-git-flow issue-start N.
  • El repositorio del tema 1 ya trae backend/ y frontend/ con su GET /api/hola: vale para comprobar que la aplicación responde.
  • Pide al agente el compose.yaml, el application.properties y el proxy.conf.json de este tema. Añade tmp/ al .gitignore.
  • deploy: pídela con su apartado y el de Segundo plano y log. Lee lo que escribe: crea tmp/db, compila con mvn clean package y lanza el backend y el frontend con nohup y & y sus logs en tmp/.
    • ./devops-desktop.sh deploy: tiene que terminar y dar la URL. Ábrela y comprueba que se ve la respuesta de /api/hola, y que existen tmp/back.log y tmp/front.log.
    • Cierra la terminal y recarga el navegador: la aplicación sigue respondiendo.
  • undeploy: pídela con su apartado y el de Segundo plano y log. Lee lo que escribe: para por puerto y no por PID, y en Windows usa taskkill con //T.
    • ./devops-desktop.sh undeploy: no queda nada en los puertos 8080 y 4200 (lsof o netstat -ano) y docker ps ya no muestra la base de datos.
  • status: pídela con su apartado.
    • ./devops-desktop.sh deploy y ./devops-desktop.sh status: tres ✓ y la URL.
    • Para solo la base de datos con docker compose stop y ./devops-desktop.sh status: ✗ solo en ella.
    • ./devops-desktop.sh undeploy y ./devops-desktop.sh status: tres ✗.
  • log: pídela con su apartado. Lee lo que escribe: tail sin -f.
    • ./devops-desktop.sh deploy y ./devops-desktop.sh log: salen las últimas líneas del arranque de Spring y la orden termina sola.
  • delete-db: pídela con su apartado. Lee lo que escribe: vacía tmp/db desde un contenedor, no con rm.
    • ./devops-desktop.sh undeploy y ./devops-desktop.sh delete-db: tmp/db queda vacía.
  • /do-git-flow commit, /do-git-flow update y, desde la carpeta principal, /do-git-flow issue-finish N.

Ejercicio 2

  • Crea el issue «Puertos de cada worktree» con /do-git-flow issue-create e inícialo con /do-git-flow issue-start N.
  • Pide al agente los cambios del apartado Puertos: application.properties, compose.yaml, proxy.conf.mjs y devops-desktop.sh (pásale En devops-desktop.sh). Lee lo que escribe: carga el .env con set -a y da a cada puerto su valor de siempre si no está. Añade .env al .gitignore.
  • ./devops-desktop.sh deploy en la carpeta principal, sin .env: sigue en el 4200. ./devops-desktop.sh undeploy.
  • Amplía /do-git-flow issue-start e issue-finish como dice /do-git-flow y la aplicación.
  • /do-git-flow commit, /do-git-flow update y, desde la carpeta principal, /do-git-flow issue-finish N.

Ejercicio 3

  • Desde la carpeta principal, crea un issue con /do-git-flow issue-create e inícialo con /do-git-flow issue-start. Comprueba que el worktree tiene su .env con los puertos del issue.
  • ./devops-desktop.sh deploy en el worktree: tiene que terminar y dar la URL con el puerto del .env. Ábrela y comprueba que se ve la respuesta de /api/hola.

Ejercicio 4

  • Vuelve a la carpeta principal, en develop, crea otro issue con /do-git-flow issue-create e inícialo con /do-git-flow issue-start N. Comprueba que su .env tiene puertos distintos de los del primero.
  • ./devops-desktop.sh deploy en el segundo worktree. Abre las dos URL: las dos aplicaciones responden a la vez.
  • ./devops-desktop.sh status en cada worktree: tres ✓ en los dos. docker ps: dos bases de datos, cada una con el nombre de su rama.

Ejercicio 5

  • ./devops-desktop.sh undeploy en el primer worktree y ./devops-desktop.sh status: tres ✗.
  • Comprueba que no queda nada en sus puertos (lsof o netstat -ano) y que la URL del segundo sigue respondiendo.

Ejercicio 6

  • ./devops-desktop.sh log en el segundo worktree: salen las últimas líneas del arranque de Spring y la orden termina sola.

Ejercicio 7

  • ./devops-desktop.sh undeploy en el segundo worktree y ./devops-desktop.sh status: tres ✗. docker ps ya no muestra ninguna base de datos de los worktrees, pero tmp/db sigue con sus ficheros.

Ejercicio 8

  • En Linux, rm -rf tmp/db en el segundo worktree: Permiso denegado.
  • ./devops-desktop.sh delete-db: tmp/db queda vacía.
  • ./devops-desktop.sh deploy y otra vez ./devops-desktop.sh delete-db: se tiene que parar porque la base de datos está arrancada. ./devops-desktop.sh undeploy.

Ejercicio 9

Aquí nace la primera entidad del proyecto, la que el tema 5 convierte en un CRUD completo.

  • Crea el issue «Entidad <entidad>: tabla, datos de prueba y listado» con /do-git-flow issue-create e inícialo con /do-git-flow issue-start N.
  • Pide al agente, en backend/, la entidad con JPA y Flyway: la migración V1__<entidad>.sql con su tabla, los datos de prueba en R__<entidad>.sql y un GET /api/<entidad> que la liste. En frontend/, la pantalla con el listado.
  • ./devops-desktop.sh undeploy, ./devops-desktop.sh delete-db y ./devops-desktop.sh deploy: la base de datos se crea desde cero y el listado muestra los datos de prueba.
  • /do-git-flow commit, /do-git-flow update y, desde la carpeta principal, /do-git-flow issue-finish N.

Ejercicio 10

Ahora que la base de datos tiene una tabla con datos, el agente puede mirarla él mismo.

  • Crea el issue «MCP de DBHub» con /do-git-flow issue-create e inícialo con /do-git-flow issue-start N.
  • Añade el MCP de DBHub en la clave mcp de opencode.json, apuntando a la base de datos del worktree: el puerto es el DB_PORT de su .env.
  • Con ./devops-desktop.sh deploy levantado, pide al agente que diga qué tablas hay y cuántas filas tiene la de tu entidad.
  • /do-git-flow commit, /do-git-flow update y, desde la carpeta principal, /do-git-flow issue-finish N.
clase/daw/daw-proyecto/tema04.txt · Última modificación: por claude