<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
  <configuration>
    <mainClass>com.nexussoftware.bibliotech.web.BiblioTechApplication</mainClass>
  </configuration>
</plugin>

./mvnw -pl bibliotech-web clean package
java -jar bibliotech-web/target/bibliotech-web-1.0.0.jar

bibliotech-web-1.0.0.jar
├── META-INF/MANIFEST.MF          ← Main-Class: org.springframework.boot.loader.launch.JarLauncher
├── org/springframework/boot/loader/   ← the loader
└── BOOT-INF/
    ├── classes/                  ← your code and your resources
    ├── lib/                      ← ~50 dependency jars
    └── classpath.idx

$ java -Djarmode=tools -jar bibliotech-web.jar list-layers
dependencies
spring-boot-loader
snapshot-dependencies
application

# Extract each layer into its own directory
java -Djarmode=tools -jar bibliotech-web.jar extract --layers --launcher --destination extracted/

<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
  <configuration>
    <layers>
      <enabled>true</enabled>
    </layers>
  </configuration>
</plugin>

<properties>
  <!-- Fixes the date of the jar entries: without this, every build differs -->
  <project.build.outputTimestamp>2026-08-05T00:00:00Z</project.build.outputTimestamp>
</properties>

./mvnw clean package
sha256sum target/bibliotech-web-1.0.0.jar
# a3f7... (the same hash on any machine, today and a year from now)

<plugin>
  <groupId>io.github.git-commit-id</groupId>
  <artifactId>git-commit-id-maven-plugin</artifactId>
  <version>9.0.1</version>
  <executions>
    <execution><goals><goal>revision</goal></goals></execution>
  </executions>
  <configuration>
    <generateGitPropertiesFile>true</generateGitPropertiesFile>
    <includeOnlyProperties>
      <property>^git.branch$</property>
      <property>^git.commit.id.abbrev$</property>
      <property>^git.commit.time$</property>
      <property>^git.build.version$</property>
    </includeOnlyProperties>
  </configuration>
</plugin>

$ curl https://bibliotech.nexussoftware.com/actuator/info
{
  "git": {
    "branch": "main",
    "commit": { "id": "a3f7e91", "time": "2026-08-05T09:14:22Z" }
  },
  "build": { "version": "1.4.2", "artifact": "bibliotech-web", "time": "2026-08-05T09:20:11Z" }
}

# ==============================================================================
# STAGE 1: BUILD
# This stage has Maven, the full JDK and the source code. None of that
# reaches the final image: it is used only to produce the jar.
# ==============================================================================
FROM eclipse-temurin:21-jdk-alpine AS builder

WORKDIR /build

# Copy ONLY the dependency files first.
# Docker caches every instruction: as long as the POMs do not change, the
# dependency download (the slowest step, 2-3 minutes) is skipped entirely.
COPY .mvn/ .mvn/
COPY mvnw pom.xml ./
COPY bibliotech-domain/pom.xml          bibliotech-domain/
COPY bibliotech-application/pom.xml     bibliotech-application/
COPY bibliotech-infrastructure/pom.xml  bibliotech-infrastructure/
COPY bibliotech-web/pom.xml             bibliotech-web/
COPY bibliotech-console/pom.xml         bibliotech-console/

# go-offline downloads every dependency without compiling anything.
# --mount=type=cache keeps ~/.m2 between builds (BuildKit).
RUN --mount=type=cache,target=/root/.m2 \
    ./mvnw -B dependency:go-offline -DskipTests

# NOW we copy the source code. If only the code changes,
# Docker reuses the previous layer and downloads nothing again.
COPY bibliotech-domain/src          bibliotech-domain/src
COPY bibliotech-application/src     bibliotech-application/src
COPY bibliotech-infrastructure/src  bibliotech-infrastructure/src
COPY bibliotech-web/src             bibliotech-web/src

# -DskipTests: the tests already ran in CI (12-05). Repeating them here
# doubles the time and would need Docker inside Docker for Testcontainers.
RUN --mount=type=cache,target=/root/.m2 \
    ./mvnw -B -pl bibliotech-web -am clean package -DskipTests

# Extract the jar into layers
RUN java -Djarmode=tools -jar bibliotech-web/target/bibliotech-web-*.jar \
         extract --layers --launcher --destination extracted

# ==============================================================================
# STAGE 2: RUNTIME
# Minimal image: JRE only (not JDK), no Maven, no source code,
# no build tools. Less surface, fewer vulnerabilities.
# ==============================================================================
FROM eclipse-temurin:21-jre-alpine AS runtime

# Standard OCI labels: metadata that ecosystem tools read
LABEL org.opencontainers.image.title="BiblioTech" \
      org.opencontainers.image.description="Nexus Software technical library" \
      org.opencontainers.image.vendor="Nexus Software" \
      org.opencontainers.image.licenses="Proprietary"

# Minimal utilities:
#  - curl for the HEALTHCHECK
#  - tzdata so time zones work (Alpine does not ship them)
#  - dumb-init as PID 1: forwards signals properly to the Java process
RUN apk add --no-cache curl tzdata dumb-init && \
    rm -rf /var/cache/apk/*

ENV TZ=Europe/Madrid

# ---- NON-root user ----
# If an attacker gets code execution, they must not have root inside the
# container. It is the cheapest and most effective mitigation there is.
RUN addgroup -S -g 1001 bibliotech && \
    adduser -S -u 1001 -G bibliotech -h /app bibliotech

WORKDIR /app

# ---- The layers, in order of stability (least changing first) ----
# Every COPY is a Docker layer. When only the code changes, only
# the last layer (~1 MB) is rebuilt and transferred.
COPY --from=builder --chown=bibliotech:bibliotech /build/extracted/dependencies/ ./
COPY --from=builder --chown=bibliotech:bibliotech /build/extracted/spring-boot-loader/ ./
COPY --from=builder --chown=bibliotech:bibliotech /build/extracted/snapshot-dependencies/ ./
COPY --from=builder --chown=bibliotech:bibliotech /build/extracted/application/ ./

USER bibliotech

EXPOSE 8080

# ---- JVM options ----
#  MaxRAMPercentage=75      uses 75% of the container limit for the heap
#  InitialRAMPercentage=50  starts at half: fewer resizes
#  UseG1GC                  balanced GC; for <2 vCPU consider SerialGC
#  ExitOnOutOfMemoryError   on OOM, die: let the orchestrator restart
#                           (a JVM in OOM serves half-broken requests, which is worse)
#  HeapDumpOnOutOfMemoryError  dump for diagnosis (10-07)
#  file.encoding=UTF-8      explicit: we do not depend on the environment
ENV JAVA_OPTS="\
    -XX:MaxRAMPercentage=75.0 \
    -XX:InitialRAMPercentage=50.0 \
    -XX:+UseG1GC \
    -XX:+ExitOnOutOfMemoryError \
    -XX:+HeapDumpOnOutOfMemoryError \
    -XX:HeapDumpPath=/tmp/heapdump.hprof \
    -Djava.security.egd=file:/dev/./urandom \
    -Dfile.encoding=UTF-8"

# Container-level health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=45s --retries=3 \
  CMD curl -fsS http://localhost:8080/actuator/health/readiness || exit 1

# dumb-init as PID 1 forwards SIGTERM to the Java process: without this,
# graceful shutdown (section 18) does not work.
ENTRYPOINT ["dumb-init", "--"]

# "shell" form so that $JAVA_OPTS is expanded. exec makes Java the
# direct child process so that it receives the signals.
CMD exec java $JAVA_OPTS org.springframework.boot.loader.launch.JarLauncher

docker build -t bibliotech:1.4.2 -t bibliotech:latest .

docker run -d --name bibliotech \
  -p 8080:8080 \
  --memory=768m --cpus=1.5 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e BIBLIOTECH_DB_URL=jdbc:postgresql://db:5432/bibliotech \
  -e BIBLIOTECH_DB_USER=bibliotech \
  -e BIBLIOTECH_DB_PASSWORD="$DB_PASSWORD" \
  bibliotech:1.4.2

docker logs -f bibliotech
docker exec bibliotech curl -s localhost:8080/actuator/health

# Everything that is not needed to build
.git/
.github/
.idea/
.vscode/
*.iml

target/
**/target/

*.md
docs/
LICENSE

# CRITICAL: none of this must enter the build context
.env
*.env
**/application-local.yml
*.pem
*.p12
*.jks
secrets/

Dockerfile
.dockerignore
compose.yaml

docker build --no-cache --progress=plain . 2>&1 | head -5
# => transferring context: 1.24MB    (good)
# Without .dockerignore it would typically be 250 MB.

./mvnw -pl bibliotech-web spring-boot:build-image \
  -Dspring-boot.build-image.imageName=bibliotech:1.4.2

<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
  <configuration>
    <image>
      <name>registry.nexussoftware.com/bibliotech:${project.version}</name>
      <env>
        <BP_JVM_VERSION>21</BP_JVM_VERSION>
        <BPE_DELIM_JAVA_TOOL_OPTIONS xml:space="preserve"> </BPE_DELIM_JAVA_TOOL_OPTIONS>
        <BPE_APPEND_JAVA_TOOL_OPTIONS>-XX:MaxRAMPercentage=75</BPE_APPEND_JAVA_TOOL_OPTIONS>
      </env>
    </image>
  </configuration>
</plugin>

<plugin>
  <groupId>com.google.cloud.tools</groupId>
  <artifactId>jib-maven-plugin</artifactId>
  <version>3.4.3</version>
  <configuration>
    <from><image>eclipse-temurin:21-jre-alpine</image></from>
    <to><image>registry.nexussoftware.com/bibliotech:${project.version}</image></to>
    <container>
      <user>1001:1001</user>
      <ports><port>8080</port></ports>
      <jvmFlags>
        <jvmFlag>-XX:MaxRAMPercentage=75.0</jvmFlag>
      </jvmFlags>
    </container>
  </configuration>
</plugin>

./mvnw -pl bibliotech-web jib:build         # pushes straight to the registry
./mvnw -pl bibliotech-web jib:dockerBuild   # or builds into the local Docker

FROM eclipse-temurin:21-jdk-alpine AS jre-minimal
RUN jlink \
    --add-modules java.base,java.logging,java.sql,java.naming,java.management,\
java.instrument,java.security.jgss,java.desktop,jdk.unsupported,jdk.crypto.ec \
    --strip-debug --no-man-pages --no-header-files --compress=2 \
    --output /jre-minimal

$ docker run --memory=512m eclipse-temurin:21-jre java -XX:+PrintFlagsFinal -version | grep MaxHeapSize
   size_t MaxHeapSize = 134217728    # 128 MB = 25% of 512 MB

docker run -e JAVA_OPTS="-XX:NativeMemoryTracking=summary" bibliotech:1.4.2
docker exec bibliotech jcmd 1 VM.native_memory summary

# compose.yaml
name: bibliotech

services:

  db:
    image: postgres:16-alpine
    container_name: bibliotech-db
    environment:
      POSTGRES_DB: bibliotech
      POSTGRES_USER: bibliotech
      POSTGRES_PASSWORD: ${DB_PASSWORD:-bibliotech}
    ports:
      - "5432:5432"
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U bibliotech -d bibliotech"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 10s

  app:
    build:
      context: .
      dockerfile: Dockerfile
    image: bibliotech:${VERSION:-dev}
    container_name: bibliotech-app
    depends_on:
      db:
        condition: service_healthy      # waits for the healthcheck, not just the start
    environment:
      SPRING_PROFILES_ACTIVE: docker
      BIBLIOTECH_DB_URL: jdbc:postgresql://db:5432/bibliotech
      BIBLIOTECH_DB_USER: bibliotech
      BIBLIOTECH_DB_PASSWORD: ${DB_PASSWORD:-bibliotech}
      JAVA_OPTS: "-XX:MaxRAMPercentage=75 -XX:+UseG1GC"
    ports:
      - "8080:8080"
    deploy:
      resources:
        limits:
          memory: 768M
          cpus: '1.5'
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/actuator/health/readiness"]
      interval: 15s
      timeout: 3s
      retries: 5
      start_period: 60s
    restart: unless-stopped

volumes:
  db-data:

docker compose up -d --build       # build and start
docker compose logs -f app         # follow the logs
docker compose ps                  # status and health
docker compose exec db psql -U bibliotech    # get into the database
docker compose down                # stop (the data survives)
docker compose down -v             # stop and DELETE the data

java -jar bibliotech-web.jar \
     --spring.config.additional-location=file:/etc/bibliotech/

apiVersion: v1
kind: ConfigMap
metadata:
  name: bibliotech-config
data:
  SPRING_PROFILES_ACTIVE: "prod"
  BIBLIOTECH_LOAN_DEFAULTDAYS: "15"
  LOGGING_LEVEL_COM_NEXUSSOFTWARE_BIBLIOTECH: "INFO"
---
apiVersion: v1
kind: Secret
metadata:
  name: bibliotech-secrets
type: Opaque
stringData:
  BIBLIOTECH_DB_PASSWORD: "…"        # managed with Sealed Secrets or an external manager
  METADATA_API_KEY: "…"

curl -s localhost:8080/actuator/env/bibliotech.fine.euros-per-day | jq
# shows the effective value AND which source it came from

<dependency>
  <groupId>org.flywaydb</groupId>
  <artifactId>flyway-core</artifactId>
</dependency>
<dependency>
  <groupId>org.flywaydb</groupId>
  <artifactId>flyway-database-postgresql</artifactId>
</dependency>

spring:
  jpa:
    hibernate:
      ddl-auto: validate        # Hibernate VERIFIES, Flyway DECIDES
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true   # for a database that already existed
    validate-on-migrate: true   # detects already-applied scripts that have changed
    out-of-order: false         # forbids applying a version older than the last one

bibliotech-infrastructure/src/main/resources/db/migration/
├── V1__initial_schema.sql
├── V2__catalog_indexes.sql
├── V3__add_material_value_column.sql
├── V4__reservations_table.sql
├── V5__return_condition_and_surcharges.sql
└── R__usage_statistics_view.sql          ← R = repeatable: re-run when it changes

-- V1__initial_schema.sql
CREATE TABLE materials (
    id                    BIGSERIAL PRIMARY KEY,
    type                  VARCHAR(20)  NOT NULL,   -- SINGLE_TABLE discriminator (ADR-004)
    isbn                  VARCHAR(17)  NOT NULL UNIQUE,
    title                 VARCHAR(200) NOT NULL,
    author                VARCHAR(150),
    publication_year      INTEGER,
    total_copies          INTEGER      NOT NULL DEFAULT 1 CHECK (total_copies >= 0),
    available_copies      INTEGER      NOT NULL DEFAULT 1 CHECK (available_copies >= 0),
    version               BIGINT       NOT NULL DEFAULT 0,   -- @Version (11-03)
    created_at            TIMESTAMPTZ  NOT NULL DEFAULT now(),
    CONSTRAINT chk_available_not_above_total
        CHECK (available_copies <= total_copies)
);

CREATE TABLE employees (
    id            BIGSERIAL PRIMARY KEY,
    name          VARCHAR(150) NOT NULL,
    email         VARCHAR(200) NOT NULL UNIQUE,
    department    VARCHAR(100),
    start_date    DATE         NOT NULL,
    version       BIGINT       NOT NULL DEFAULT 0
);

CREATE TABLE loans (
    id                 BIGSERIAL PRIMARY KEY,
    material_id        BIGINT      NOT NULL REFERENCES materials(id),
    employee_id        BIGINT      NOT NULL REFERENCES employees(id),
    loan_date          DATE        NOT NULL,
    due_date           DATE        NOT NULL,
    return_date        DATE,
    status             VARCHAR(20) NOT NULL,
    version            BIGINT      NOT NULL DEFAULT 0,
    CONSTRAINT chk_due_after_loan CHECK (due_date >= loan_date),
    CONSTRAINT chk_return_after_loan
        CHECK (return_date IS NULL OR return_date >= loan_date)
);

-- Indexes for the queries that are actually made
CREATE INDEX idx_loans_employee_status ON loans(employee_id, status);
CREATE INDEX idx_loans_due_date        ON loans(due_date)
                                       WHERE return_date IS NULL;        -- partial
CREATE INDEX idx_materials_title       ON materials USING gin(to_tsvector('english', title));

-- Reference data the application needs in order to start
INSERT INTO employees (name, email, department, start_date) VALUES
    ('Marta Ruiz',  '[email protected]',  'Architecture', '2024-03-01'),
    ('Diego Alonso','[email protected]','Backend',      '2025-01-15'),
    ('Nuria Vidal', '[email protected]', 'Platform',     '2023-09-10');

./mvnw flyway:info       # which migrations exist and which are applied
./mvnw flyway:validate   # checks the checksums
./mvnw flyway:migrate    # applies the pending ones
./mvnw flyway:repair     # fixes the control table (carefully!)

@Test
void allMigrationsApplyOnACleanPostgres() {
    Flyway flyway = Flyway.configure()
            .dataSource(POSTGRES.getJdbcUrl(), POSTGRES.getUsername(), POSTGRES.getPassword())
            .locations("classpath:db/migration")
            .load();

    MigrateResult result = flyway.migrate();

    assertThat(result.success).isTrue();
    assertThat(result.migrationsExecuted).isGreaterThan(0);
    // And that the resulting schema matches what Hibernate expects:
    assertThatNoException().isThrownBy(() -> validateSchemaAgainstEntities());
}

-- V6__rename_column.sql
ALTER TABLE loans RENAME COLUMN due_dt TO due_date;

-- PHASE 1: V6__add_due_date.sql   (compatible with app v1)
ALTER TABLE loans ADD COLUMN due_date DATE;

UPDATE loans SET due_date = due_dt WHERE due_date IS NULL;

-- Dual-write trigger: it does not matter which app version writes
CREATE OR REPLACE FUNCTION sync_due_date() RETURNS TRIGGER AS $$
BEGIN
    IF NEW.due_date IS DISTINCT FROM OLD.due_date THEN
        NEW.due_dt := NEW.due_date;
    ELSIF NEW.due_dt IS DISTINCT FROM OLD.due_dt THEN
        NEW.due_date := NEW.due_dt;
    END IF;
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trg_sync_due_date
    BEFORE INSERT OR UPDATE ON loans
    FOR EACH ROW EXECUTE FUNCTION sync_due_date();

-- PHASE 3: V8__drop_due_dt.sql   (only after confirming v1 is no longer running)
DROP TRIGGER IF EXISTS trg_sync_due_date ON loans;
DROP FUNCTION IF EXISTS sync_due_date();
ALTER TABLE loans DROP COLUMN due_dt;
ALTER TABLE loans ALTER COLUMN due_date SET NOT NULL;

# /etc/systemd/system/bibliotech.service
[Unit]
Description=BiblioTech - Nexus Software technical library
After=network.target postgresql.service
Wants=postgresql.service

[Service]
Type=simple
User=bibliotech
Group=bibliotech
WorkingDirectory=/opt/bibliotech

EnvironmentFile=/etc/bibliotech/environment   # secrets, with 600 permissions
ExecStart=/usr/bin/java $JAVA_OPTS -jar /opt/bibliotech/bibliotech-web.jar

SuccessExitStatus=143                        # 128 + SIGTERM: graceful shutdown, not a failure
Restart=on-failure
RestartSec=10

# Graceful shutdown: SIGTERM, and 60 s before SIGKILL
KillSignal=SIGTERM
TimeoutStopSec=60

# Hardening: least privilege (12-07)
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/log/bibliotech /var/lib/bibliotech

StandardOutput=journal
StandardError=journal
SyslogIdentifier=bibliotech

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now bibliotech
sudo systemctl status bibliotech
sudo journalctl -u bibliotech -f

apiVersion: apps/v1
kind: Deployment
metadata:
  name: bibliotech
  labels:
    app: bibliotech
spec:
  replicas: 3                       # three instances: high availability
  revisionHistoryLimit: 5           # history for rollback

  strategy:
    type: RollingUpdate             # rolling update (section 20)
    rollingUpdate:
      maxSurge: 1                   # at most 1 extra pod during the transition
      maxUnavailable: 0             # NEVER fewer than 3 available: no service interruption

  selector:
    matchLabels:
      app: bibliotech

  template:
    metadata:
      labels:
        app: bibliotech
        version: "1.4.2"
    spec:
      # Room for the graceful shutdown to finish (section 18)
      terminationGracePeriodSeconds: 60

      securityContext:              # least privilege at pod level
        runAsNonRoot: true
        runAsUser: 1001
        fsGroup: 1001

      containers:
        - name: bibliotech
          image: registry.nexussoftware.com/bibliotech:1.4.2   # EXACT tag, never 'latest'
          imagePullPolicy: IfNotPresent

          ports:
            - name: http
              containerPort: 8080

          envFrom:
            - configMapRef: { name: bibliotech-config }
            - secretRef:    { name: bibliotech-secrets }

          resources:
            requests:                # what the scheduler reserves
              memory: "512Mi"
              cpu: "250m"
            limits:                  # the ceiling; exceeding it on memory = OOMKilled
              memory: "768Mi"
              cpu: "1500m"

          # --- Probes (section 17) ---
          startupProbe:              # protects startup: up to 100 s
            httpGet: { path: /actuator/health/liveness, port: http }
            failureThreshold: 20
            periodSeconds: 5

          livenessProbe:             # still alive? If not, RESTART
            httpGet: { path: /actuator/health/liveness, port: http }
            periodSeconds: 10
            failureThreshold: 3

          readinessProbe:            # can it serve? If not, TAKE IT OUT OF THE BALANCER
            httpGet: { path: /actuator/health/readiness, port: http }
            periodSeconds: 5
            failureThreshold: 2

          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true       # nothing writes to the root
            capabilities: { drop: ["ALL"] }

          volumeMounts:
            - name: tmp
              mountPath: /tmp                  # required: Tomcat and the dumps write here

      volumes:
        - name: tmp
          emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
  name: bibliotech
spec:
  selector:
    app: bibliotech
  ports:
    - port: 80
      targetPort: http
  type: ClusterIP
---
apiVersion: policy/v1
kind: PodDisruptionBudget           # protects during cluster maintenance
metadata:
  name: bibliotech
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: bibliotech

kubectl apply -f k8s/
kubectl rollout status deployment/bibliotech
kubectl get pods -l app=bibliotech
kubectl logs -f -l app=bibliotech --tail=100
kubectl rollout undo deployment/bibliotech         # immediate rollback

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus     # ONLY what is needed (12-07)
      base-path: /actuator
  endpoint:
    health:
      probes:
        enabled: true                # enables /health/liveness and /health/readiness
      show-details: when-authorized  # the detail, only to whoever is allowed
      group:
        readiness:
          include: db, diskSpace     # if the DB does not answer, we are not ready
        liveness:
          include: livenessState     # only the process state
  health:
    livenessstate:
      enabled: true
    readinessstate:
      enabled: true

$ curl localhost:8080/actuator/health/liveness
{"status":"UP"}

$ curl localhost:8080/actuator/health/readiness
{"status":"UP","components":{"db":{"status":"UP"},"diskSpace":{"status":"UP"}}}

@Component
public class MetadataGatewayHealth implements HealthIndicator {

    private final MetadataGateway gateway;

    @Override
    public Health health() {
        try {
            boolean available = gateway.checkAvailability();
            return available
                    ? Health.up().withDetail("gateway", "available").build()
                    // DEGRADED, not DOWN: the application works without external metadata.
                    // Marking DOWN here would pull a perfectly usable app out of the balancer.
                    : Health.status("DEGRADED").withDetail("gateway", "not responding").build();
        } catch (Exception e) {
            return Health.status("DEGRADED").withException(e).build();
        }
    }
}

server:
  shutdown: graceful            # stops accepting new requests and waits for the current ones

spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

@Component
public class GracefulShutdown {

    private static final Logger log = LoggerFactory.getLogger(GracefulShutdown.class);

    private final ExecutorService importExecutor;

    /**
     * @PreDestroy runs when the Spring context closes,
     * which is what happens on receiving SIGTERM.
     */
    @PreDestroy
    public void onShutdown() {
        log.info("Graceful shutdown: closing resources");

        importExecutor.shutdown();            // accepts no new tasks
        try {
            if (!importExecutor.awaitTermination(20, TimeUnit.SECONDS)) {
                log.warn("Imports unfinished after 20 s; forcing");
                importExecutor.shutdownNow();
            }
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            importExecutor.shutdownNow();
        }
        log.info("Graceful shutdown complete");
    }
}

lifecycle:
  preStop:
    exec:
      command: ["sh", "-c", "sleep 10"]     # give the balancer time to update

# Generate the CDS archive during the image build
RUN java -XX:ArchiveClassesAtExit=/app/app.jsa \
         -Dspring.context.exit=onRefresh \
         org.springframework.boot.loader.launch.JarLauncher

ENV JAVA_OPTS="$JAVA_OPTS -XX:SharedArchiveFile=/app/app.jsa"

<profile>
  <id>native</id>
  <build>
    <plugins>
      <plugin>
        <groupId>org.graalvm.buildtools</groupId>
        <artifactId>native-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</profile>

./mvnw -Pnative native:compile -pl bibliotech-web
./bibliotech-web/target/bibliotech-web       # starts in 80 ms

@Service
public class LoanManager {

    private final BiblioTechProperties props;

    public Loan lend(Isbn isbn, Long employeeId, Integer days) {
        if (props.features().autoReservation()) {
            // New code, deployed but switched off until somebody decides
            return lendWithAutoReservation(isbn, employeeId, days);
        }
        return lendClassic(isbn, employeeId, days);
    }
}

bibliotech:
  features:
    auto-reservation: false          # switched on with an environment variable, no deployment
    priority-loan: true
    pdf-report: false

kubectl rollout undo deployment/bibliotech
docker compose up -d --force-recreate   # with the previous tag
sudo systemctl stop bibliotech && cp bibliotech-1.4.1.jar bibliotech-web.jar && sudo systemctl start bibliotech

# Daily backup
pg_dump -h db -U bibliotech -Fc bibliotech > bibliotech-$(date +%F).dump

# Backup before ANY destructive migration
pg_dump -h db -U bibliotech -Fc bibliotech > pre-migration-v8-$(date +%F-%H%M).dump

# .github/workflows/cd.yml
name: Continuous delivery

on:
  push:
    branches: [main]
    tags: ['v*']

env:
  REGISTRY: ghcr.io
  IMAGE: ${{ github.repository }}

permissions:
  contents: read
  packages: write
  id-token: write          # to sign the image with cosign

jobs:

  # ---------------------------------------------------------------
  # 1. Reuses the full verification from 12-05
  # ---------------------------------------------------------------
  verify:
    uses: ./.github/workflows/ci.yml

  # ---------------------------------------------------------------
  # 2. Build and publish the image
  # ---------------------------------------------------------------
  image:
    name: Build and publish image
    runs-on: ubuntu-latest
    needs: verify
    outputs:
      digest: ${{ steps.build.outputs.digest }}
      tags: ${{ steps.meta.outputs.tags }}

    steps:
      - uses: actions/checkout@v4

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3        # to build for arm64

      - name: Set up Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to the registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Compute tags and metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE }}
          tags: |
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=sha,prefix=,format=short          # traceability to the commit
            type=raw,value=latest,enable={{is_default_branch}}

      - name: Build and push
        id: build
        uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha                    # layer cache between runs
          cache-to: type=gha,mode=max
          provenance: true
          sbom: true                              # component inventory (12-07)

      - name: Scan the image for vulnerabilities
        uses: aquasecurity/[email protected]
        with:
          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE }}@${{ steps.build.outputs.digest }}
          severity: 'CRITICAL,HIGH'
          exit-code: '1'                          # blocks if there are serious vulnerabilities

      - name: Sign the image
        uses: sigstore/cosign-installer@v3
      - run: cosign sign --yes ${{ env.REGISTRY }}/${{ env.IMAGE }}@${{ steps.build.outputs.digest }}

  # ---------------------------------------------------------------
  # 3. Staging: automatic
  # ---------------------------------------------------------------
  staging:
    name: Deploy to staging
    runs-on: ubuntu-latest
    needs: image
    environment:
      name: staging
      url: https://staging.bibliotech.nexussoftware.com

    steps:
      - name: Deploy
        run: |
          kubectl set image deployment/bibliotech \
            bibliotech=${{ env.REGISTRY }}/${{ env.IMAGE }}@${{ needs.image.outputs.digest }} \
            --namespace=staging
          kubectl rollout status deployment/bibliotech -n staging --timeout=5m

      - name: Smoke tests
        run: |
          BASE=https://staging.bibliotech.nexussoftware.com
          curl -fsS "$BASE/actuator/health/readiness" | jq -e '.status == "UP"'
          curl -fsS "$BASE/api/materials?size=1"      | jq -e '.content | length >= 0'
          echo "Smoke tests passed"

  # ---------------------------------------------------------------
  # 4. Production: requires manual approval
  # ---------------------------------------------------------------
  production:
    name: Deploy to production
    runs-on: ubuntu-latest
    needs: [image, staging]
    if: startsWith(github.ref, 'refs/tags/v')     # only from a version tag
    environment:
      name: production                            # with required reviewers configured
      url: https://bibliotech.nexussoftware.com

    steps:
      - name: Record the current revision, in case we have to go back
        id: current
        run: |
          CURRENT=$(kubectl get deployment/bibliotech -n production \
                    -o jsonpath='{.spec.template.spec.containers[0].image}')
          echo "previous_image=$CURRENT" >> $GITHUB_OUTPUT

      - name: Deploy (rolling update)
        run: |
          kubectl set image deployment/bibliotech \
            bibliotech=${{ env.REGISTRY }}/${{ env.IMAGE }}@${{ needs.image.outputs.digest }} \
            --namespace=production
          kubectl rollout status deployment/bibliotech -n production --timeout=10m

      - name: Verify health after the deployment
        id: verify
        run: |
          sleep 30
          BASE=https://bibliotech.nexussoftware.com
          for i in $(seq 1 10); do
            if curl -fsS "$BASE/actuator/health/readiness" | jq -e '.status == "UP"' > /dev/null; then
              echo "Instance healthy (attempt $i)"; sleep 5
            else
              echo "::error::Health verification failed"; exit 1
            fi
          done
          # Check that the error rate has not shot up
          ERRORS=$(curl -fsS "$BASE/actuator/metrics/http.server.requests?tag=outcome:SERVER_ERROR" \
                   | jq '.measurements[0].value // 0')
          if (( $(echo "$ERRORS > 10" | bc -l) )); then
            echo "::error::Too many 5xx errors after the deployment"; exit 1
          fi

      - name: Automatic rollback if something failed
        if: failure()
        run: |
          echo "::warning::Deployment failed; going back to the previous version"
          kubectl rollout undo deployment/bibliotech -n production
          kubectl rollout status deployment/bibliotech -n production --timeout=5m

      - name: Report the result
        if: always()
        run: |
          STATUS="${{ job.status }}"
          curl -X POST "${{ secrets.TEAM_WEBHOOK }}" \
            -H 'Content-Type: application/json' \
            -d "{\"text\":\"BiblioTech deployment ${{ github.ref_name }}: $STATUS\"}"

// WITH 3 INSTANCES: this sends THREE notices to every employee, every day
@Scheduled(cron = "0 0 8 * * *")
public void sendDailyNotices() {
    noticeService.notifyUpcomingDueDates(3);
}

// Option A: ShedLock — a distributed lock in the database
@Scheduled(cron = "0 0 8 * * *")
@SchedulerLock(name = "dailyNotices", lockAtMostFor = "10m", lockAtLeastFor = "1m")
public void sendDailyNotices() {
    noticeService.notifyUpcomingDueDates(3);
}

# Option B: a Kubernetes CronJob that invokes the CLI from 12-03.
# Advantage: the scheduler does not live inside the application.
apiVersion: batch/v1
kind: CronJob
metadata:
  name: bibliotech-notices
spec:
  schedule: "0 8 * * *"
  concurrencyPolicy: Forbid           # do not overlap runs
  jobTemplate:
    spec:
      backoffLimit: 3
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: cli
              image: registry.nexussoftware.com/bibliotech-cli:1.4.2
              args: ["notices", "send", "--days-ahead=3"]
              envFrom:
                - secretRef: { name: bibliotech-secrets }

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: bibliotech
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: bibliotech
  minReplicas: 3
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target: { type: Utilization, averageUtilization: 70 }
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300     # do not scale down on the first dip: avoids flapping

# ==============================================================================
# STAGE 1: BUILD
# ==============================================================================
FROM eclipse-temurin:21-jdk-alpine AS builder

WORKDIR /build

COPY .mvn/ .mvn/
COPY mvnw pom.xml ./
COPY bibliotech-domain/pom.xml          bibliotech-domain/
COPY bibliotech-application/pom.xml     bibliotech-application/
COPY bibliotech-infrastructure/pom.xml  bibliotech-infrastructure/
COPY bibliotech-console/pom.xml         bibliotech-console/

RUN --mount=type=cache,target=/root/.m2 \
    ./mvnw -B -pl bibliotech-console -am dependency:go-offline -DskipTests

COPY bibliotech-domain/src          bibliotech-domain/src
COPY bibliotech-application/src     bibliotech-application/src
COPY bibliotech-infrastructure/src  bibliotech-infrastructure/src
COPY bibliotech-console/src         bibliotech-console/src

RUN --mount=type=cache,target=/root/.m2 \
    ./mvnw -B -pl bibliotech-console -am clean package -DskipTests

RUN java -Djarmode=tools -jar bibliotech-console/target/bibliotech-cli.jar \
         extract --layers --launcher --destination extracted

# ==============================================================================
# STAGE 2: GENERATE THE CDS ARCHIVE
# The application is run once with --help so that it loads the classes,
# and the result is memorised. This trims ~1.5 s off every startup, which
# multiplied by the cron runs does matter.
# ==============================================================================
FROM eclipse-temurin:21-jre-alpine AS cds

WORKDIR /app
COPY --from=builder /build/extracted/ ./

RUN java -XX:ArchiveClassesAtExit=/app/cli.jsa \
         org.springframework.boot.loader.launch.JarLauncher --help > /dev/null 2>&1 || true

# ==============================================================================
# STAGE 3: RUNTIME
# ==============================================================================
FROM eclipse-temurin:21-jre-alpine AS runtime

LABEL org.opencontainers.image.title="BiblioTech CLI" \
      org.opencontainers.image.description="BiblioTech command-line tool" \
      org.opencontainers.image.vendor="Nexus Software"

# tzdata for the dates; dumb-init so that Ctrl+C and SIGTERM reach the process
# (the clean cancellation from 12-03 depends on this).
# curl is NOT installed: there is no healthcheck to run.
RUN apk add --no-cache tzdata dumb-init && rm -rf /var/cache/apk/*
ENV TZ=Europe/Madrid

RUN addgroup -S -g 1001 bibliotech && \
    adduser -S -u 1001 -G bibliotech -h /app bibliotech

WORKDIR /app

COPY --from=cds --chown=bibliotech:bibliotech /app/ ./

USER bibliotech

# Options AIMED AT STARTUP, not at sustained throughput.
# The process lives seconds: compiling fully with C2 never pays for itself.
#   TieredStopAtLevel=1    C1 only: fast, lightweight compilation
#   UseSerialGC            the cheapest GC to initialise (one task, little memory)
#   SharedArchiveFile      uses the CDS from stage 2
#   MaxRAMPercentage=75    cgroup-aware, as always
ENV JAVA_OPTS="\
    -XX:TieredStopAtLevel=1 \
    -XX:+UseSerialGC \
    -XX:SharedArchiveFile=/app/cli.jsa \
    -XX:MaxRAMPercentage=75.0 \
    -Xshare:auto \
    -Dspring.main.banner-mode=off \
    -Dfile.encoding=UTF-8"

# NO EXPOSE: the CLI listens on no port.
# NO HEALTHCHECK: the process exits; there is nothing to watch.

ENTRYPOINT ["dumb-init", "--", "sh", "-c", \
            "exec java $JAVA_OPTS org.springframework.boot.loader.launch.JarLauncher \"$@\"", "--"]

# CMD holds the DEFAULT arguments, replaceable at run time
CMD ["--help"]

docker build -f Dockerfile.cli -t bibliotech-cli:1.4.2 .

docker run --rm bibliotech-cli:1.4.2 catalog list --format=json
docker run --rm -e BIBLIOTECH_DB_URL=… bibliotech-cli:1.4.2 notices send --days-ahead=3

# Check the effect of CDS
docker run --rm bibliotech-cli:1.4.2 --version   # ~1.1 s instead of ~2.6 s

apiVersion: batch/v1
kind: CronJob
metadata:
  name: bibliotech-daily-notices
  labels:
    app: bibliotech
    component: scheduled-tasks
spec:
  schedule: "0 8 * * 1-5"           # Monday to Friday at 8:00
  timeZone: "Europe/Madrid"         # Kubernetes 1.27+: essential with daylight saving

  concurrencyPolicy: Forbid         # if the previous one is still running, do NOT start another
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 5
  startingDeadlineSeconds: 600      # if the cluster was down, there is a 10 min margin

  jobTemplate:
    spec:
      backoffLimit: 2               # 2 retries on failure
      activeDeadlineSeconds: 900    # kill it if it exceeds 15 minutes
      ttlSecondsAfterFinished: 86400

      template:
        metadata:
          labels:
            app: bibliotech
            task: notices
        spec:
          restartPolicy: OnFailure

          securityContext:
            runAsNonRoot: true
            runAsUser: 1001

          containers:
            - name: cli
              image: registry.nexussoftware.com/bibliotech-cli:1.4.2
              imagePullPolicy: IfNotPresent

              args:
                - "notices"
                - "send"
                - "--days-ahead=3"
                - "--quiet"            # no decoration: the output goes to the log

              envFrom:
                - configMapRef: { name: bibliotech-config }
                - secretRef:    { name: bibliotech-secrets }

              resources:
                requests: { memory: "256Mi", cpu: "100m" }
                limits:   { memory: "512Mi", cpu: "1000m" }

              securityContext:
                allowPrivilegeEscalation: false
                readOnlyRootFilesystem: true
                capabilities: { drop: ["ALL"] }

              volumeMounts:
                - name: tmp
                  mountPath: /tmp

          volumes:
            - name: tmp
              emptyDir: {}

kubectl get cronjob bibliotech-daily-notices
kubectl create job --from=cronjob/bibliotech-daily-notices manual-run   # run it now
kubectl logs job/manual-run

-- V9__split_employee_name_phase1.sql

ALTER TABLE employees ADD COLUMN first_name VARCHAR(80);
ALTER TABLE employees ADD COLUMN surname    VARCHAR(120);

-- Populate with a conservative heuristic:
-- the FIRST word is the given name; the rest is the surname.
-- It is imperfect for compound names ("José María"), which is why
-- the original column is kept and a review report is produced.
UPDATE employees
SET first_name = split_part(trim(name), ' ', 1),
    surname    = NULLIF(trim(substring(trim(name) from position(' ' in trim(name)) + 1)), '')
WHERE first_name IS NULL;

-- Special case: a single term (no spaces) → it is all given name
UPDATE employees
SET first_name = trim(name), surname = NULL
WHERE position(' ' in trim(name)) = 0;

-- Bidirectional sync trigger: it does not matter which app version writes
CREATE OR REPLACE FUNCTION sync_employee_name() RETURNS TRIGGER AS $$
BEGIN
    IF TG_OP = 'INSERT' THEN
        IF NEW.first_name IS NULL AND NEW.name IS NOT NULL THEN
            -- App v1 wrote (old column): derive the new ones
            NEW.first_name := split_part(trim(NEW.name), ' ', 1);
            NEW.surname    := NULLIF(trim(substring(trim(NEW.name)
                                   from position(' ' in trim(NEW.name)) + 1)), '');
        ELSIF NEW.name IS NULL AND NEW.first_name IS NOT NULL THEN
            -- App v2 wrote (new columns): derive the old one
            NEW.name := trim(NEW.first_name || ' ' || COALESCE(NEW.surname, ''));
        END IF;
    ELSIF TG_OP = 'UPDATE' THEN
        IF NEW.name IS DISTINCT FROM OLD.name THEN
            NEW.first_name := split_part(trim(NEW.name), ' ', 1);
            NEW.surname    := NULLIF(trim(substring(trim(NEW.name)
                                   from position(' ' in trim(NEW.name)) + 1)), '');
        ELSIF NEW.first_name IS DISTINCT FROM OLD.first_name
           OR NEW.surname    IS DISTINCT FROM OLD.surname THEN
            NEW.name := trim(NEW.first_name || ' ' || COALESCE(NEW.surname, ''));
        END IF;
    END IF;
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trg_sync_employee_name
    BEFORE INSERT OR UPDATE ON employees
    FOR EACH ROW EXECUTE FUNCTION sync_employee_name();

-- Manual review view: the cases the heuristic probably got wrong
CREATE OR REPLACE VIEW v_employees_name_review AS
SELECT id, name, first_name, surname,
       CASE
         WHEN first_name IN ('José','Jose','María','Maria','Juan','Ana','Luis','Francisco')
              AND surname LIKE '% %'                     THEN 'possible compound given name'
         WHEN surname ~ '^(de|del|la|las|los|van|von|di|da) ' THEN 'surname with particle'
         WHEN surname IS NULL                            THEN 'no surname'
         ELSE 'review'
       END AS reason
FROM employees
WHERE first_name IN ('José','Jose','María','Maria','Juan','Ana','Luis','Francisco')
   OR surname ~ '^(de|del|la|las|los|van|von|di|da) '
   OR surname IS NULL;

@Entity
public class Employee {

    @Column(name = "first_name", length = 80)
    private String firstName;

    @Column(name = "surname", length = 120)
    private String surname;

    /**
     * The old column still exists and the trigger maintains it.
     * insertable/updatable false: JPA NEVER writes it.
     * It is kept mapped only so that it can be read if ever needed.
     */
    @Column(name = "name", insertable = false, updatable = false)
    private String legacyFullName;

    public String fullName() {
        return surname == null ? firstName : firstName + " " + surname;
    }
}

-- V11__split_employee_name_phase3.sql

-- Pre-check: if anything ended up inconsistent, ABORT
DO $$
DECLARE inconsistent INTEGER;
BEGIN
    SELECT count(*) INTO inconsistent
    FROM employees
    WHERE first_name IS NULL
       OR trim(name) IS DISTINCT FROM trim(first_name || ' ' || COALESCE(surname, ''));

    IF inconsistent > 0 THEN
        RAISE EXCEPTION 'There are % employees with an inconsistent name. Check v_employees_name_review before contracting.', inconsistent;
    END IF;
END $$;

DROP TRIGGER IF EXISTS trg_sync_employee_name ON employees;
DROP FUNCTION IF EXISTS sync_employee_name();
DROP VIEW IF EXISTS v_employees_name_review;

ALTER TABLE employees ALTER COLUMN first_name SET NOT NULL;
ALTER TABLE employees DROP COLUMN name;

CREATE INDEX idx_employees_surname ON employees(surname, first_name);

@Tag("integration")
class EmployeeNameMigrationIT extends PostgresTestBase {

    @Test
    void splitsTheKnownNamesCorrectly() {
        // Initial state: up to V8, with the old column
        flywayUpTo("8");
        jdbc.update("""
                insert into employees (name, email, start_date) values
                    ('Marta Ruiz',              '[email protected]',  '2024-03-01'),
                    ('Diego Alonso',            '[email protected]',  '2025-01-15'),
                    ('Nuria Vidal',             '[email protected]',  '2023-09-10'),
                    ('José María Pérez Gómez',  '[email protected]',   '2022-05-20'),
                    ('Ana de la Torre',         '[email protected]',    '2021-11-02'),
                    ('Prince',                  '[email protected]', '2020-01-01')
                """);

        flywayUpTo("9");      // apply phase 1

        assertThat(namesOf("[email protected]"))
                .containsExactly("Marta", "Ruiz");
        assertThat(namesOf("[email protected]"))
                .containsExactly("Nuria", "Vidal");

        // Hard cases: the heuristic splits them wrongly, and that is EXPECTED
        assertThat(namesOf("[email protected]"))
                .containsExactly("José", "María Pérez Gómez");     // needs manual review
        assertThat(namesOf("[email protected]"))
                .containsExactly("Ana", "de la Torre");

        // A single term
        assertThat(namesOf("[email protected]"))
                .containsExactly("Prince", null);

        // And they all appear in the review view, which is what matters:
        // the migration does not aim to always get it right, it aims NOT TO LOSE DATA
        // and to flag what needs reviewing.
        assertThat(jdbc.queryForList("select email from v_employees_name_review", String.class))
                .contains("[email protected]", "[email protected]",
                          "[email protected]");
    }

    @Test
    void theTriggerSyncsInBothDirections() {
        flywayUpTo("9");

        // App v1 writes the old column
        jdbc.update("insert into employees (name, email, start_date) values (?,?,?)",
                    "Carlos Sanz", "[email protected]", Date.valueOf("2026-01-01"));
        assertThat(namesOf("[email protected]")).containsExactly("Carlos", "Sanz");

        // App v2 writes the new columns
        jdbc.update("""
                insert into employees (first_name, surname, email, start_date)
                values (?,?,?,?)""",
                "Elena", "Ferrer Rico", "[email protected]", Date.valueOf("2026-01-02"));
        assertThat(jdbc.queryForObject(
                "select name from employees where email = ?", String.class,
                "[email protected]"))
                .isEqualTo("Elena Ferrer Rico");
    }

    @Test
    void phase3AbortsIfInconsistenciesRemain() {
        flywayUpTo("9");
        // Force an inconsistency by bypassing the trigger
        jdbc.update("alter table employees disable trigger trg_sync_employee_name");
        jdbc.update("insert into employees (name, email, start_date) values (?,?,?)",
                    "Not Split", "[email protected]", Date.valueOf("2026-01-03"));
        jdbc.update("alter table employees enable trigger trg_sync_employee_name");

        assertThatThrownBy(() -> flywayUpTo("11"))
                .hasMessageContaining("inconsistent name");

        // And most important of all: the old column IS STILL THERE. Nothing has been lost.
        assertThat(columnExists("employees", "name")).isTrue();
    }
}

# k8s/blue-green/service.yaml
# The Service points at ONE colour. Switching = changing the selector.
apiVersion: v1
kind: Service
metadata:
  name: bibliotech
  labels: { app: bibliotech }
spec:
  selector:
    app: bibliotech
    colour: blue               # ← this is what changes on the switch
  ports:
    - port: 80
      targetPort: 8080
---
# Auxiliary Service to test the idle colour WITHOUT real traffic
apiVersion: v1
kind: Service
metadata:
  name: bibliotech-preview
spec:
  selector:
    app: bibliotech
    colour: green              # adjusted before the smoke tests
  ports:
    - port: 80
      targetPort: 8080
---
# k8s/blue-green/deployment-template.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: bibliotech-COLOUR
  labels: { app: bibliotech, colour: COLOUR }
spec:
  replicas: 3
  selector:
    matchLabels: { app: bibliotech, colour: COLOUR }
  template:
    metadata:
      labels: { app: bibliotech, colour: COLOUR }
    spec:
      terminationGracePeriodSeconds: 60
      containers:
        - name: bibliotech
          image: IMAGE
          ports: [{ name: http, containerPort: 8080 }]
          envFrom:
            - configMapRef: { name: bibliotech-config }
            - secretRef:    { name: bibliotech-secrets }
          resources:
            requests: { memory: "512Mi", cpu: "250m" }
            limits:   { memory: "768Mi", cpu: "1500m" }
          startupProbe:
            httpGet: { path: /actuator/health/liveness, port: http }
            failureThreshold: 20
            periodSeconds: 5
          readinessProbe:
            httpGet: { path: /actuator/health/readiness, port: http }
            periodSeconds: 5

# .github/workflows/cd-blue-green.yml
name: Blue-green deployment

on:
  push:
    tags: ['v*']

env:
  NAMESPACE: production
  REGISTRY: ghcr.io
  IMAGE: ${{ github.repository }}

jobs:

  # ---------------------------------------------------------------
  # 1. Determine the colours
  # ---------------------------------------------------------------
  colours:
    runs-on: ubuntu-latest
    outputs:
      active: ${{ steps.detect.outputs.active }}
      idle:   ${{ steps.detect.outputs.idle }}
    steps:
      - name: Set up kubectl
        uses: azure/k8s-set-context@v4
        with:
          kubeconfig: ${{ secrets.KUBECONFIG }}

      - name: Detect the active colour
        id: detect
        run: |
          ACTIVE=$(kubectl get service bibliotech -n $NAMESPACE \
                   -o jsonpath='{.spec.selector.colour}')
          if [ "$ACTIVE" = "blue" ]; then IDLE="green"; else IDLE="blue"; fi
          echo "active=$ACTIVE" >> $GITHUB_OUTPUT
          echo "idle=$IDLE"     >> $GITHUB_OUTPUT
          echo "::notice::Active: $ACTIVE — will deploy to: $IDLE"

  # ---------------------------------------------------------------
  # 2. Deploy to the idle colour (no traffic)
  # ---------------------------------------------------------------
  deploy-idle:
    runs-on: ubuntu-latest
    needs: colours
    steps:
      - uses: actions/checkout@v4
      - uses: azure/k8s-set-context@v4
        with: { kubeconfig: '${{ secrets.KUBECONFIG }}' }

      - name: Render and apply the idle colour's Deployment
        run: |
          COLOUR=${{ needs.colours.outputs.idle }}
          IMG=${{ env.REGISTRY }}/${{ env.IMAGE }}:${{ github.ref_name }}

          sed -e "s|COLOUR|$COLOUR|g" -e "s|IMAGE|$IMG|g" \
              k8s/blue-green/deployment-template.yaml | kubectl apply -n $NAMESPACE -f -

          kubectl rollout status deployment/bibliotech-$COLOUR -n $NAMESPACE --timeout=10m

      - name: Point the preview Service at the idle colour
        run: |
          kubectl patch service bibliotech-preview -n $NAMESPACE \
            -p '{"spec":{"selector":{"app":"bibliotech","colour":"${{ needs.colours.outputs.idle }}"}}}'

  # ---------------------------------------------------------------
  # 3. Smoke tests against the idle colour
  # ---------------------------------------------------------------
  smoke:
    runs-on: ubuntu-latest
    needs: [colours, deploy-idle]
    steps:
      - uses: azure/k8s-set-context@v4
        with: { kubeconfig: '${{ secrets.KUBECONFIG }}' }

      - name: Run the tests against the idle colour
        run: |
          kubectl port-forward service/bibliotech-preview 18080:80 -n $NAMESPACE &
          PF=$!
          sleep 8
          set -e

          BASE=http://localhost:18080

          echo "→ Health"
          curl -fsS "$BASE/actuator/health/readiness" | jq -e '.status == "UP"'

          echo "→ Deployed version"
          VERSION=$(curl -fsS "$BASE/actuator/info" | jq -r '.build.version')
          test "v$VERSION" = "${{ github.ref_name }}" \
            || { echo "::error::Unexpected version: $VERSION"; exit 1; }

          echo "→ Catalogue"
          curl -fsS "$BASE/api/materials?size=1" | jq -e '.content | length >= 0'

          echo "→ Expected errors (404 and 400)"
          test "$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/materials/978-9999999999")" = "404"
          test "$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/materials/not-an-isbn")" = "400"

          kill $PF
          echo "Smoke tests passed"

  # ---------------------------------------------------------------
  # 4. Switch the traffic (with manual approval)
  # ---------------------------------------------------------------
  switch:
    runs-on: ubuntu-latest
    needs: [colours, smoke]
    environment:
      name: production          # with required reviewers
      url: https://bibliotech.nexussoftware.com
    steps:
      - uses: azure/k8s-set-context@v4
        with: { kubeconfig: '${{ secrets.KUBECONFIG }}' }

      - name: Switch the Service to the new colour
        run: |
          kubectl patch service bibliotech -n $NAMESPACE \
            -p '{"spec":{"selector":{"app":"bibliotech","colour":"${{ needs.colours.outputs.idle }}"}}}'
          echo "::notice::Traffic switched to ${{ needs.colours.outputs.idle }}"

  # ---------------------------------------------------------------
  # 5. Watch for 5 minutes; roll back if the error rate rises
  # ---------------------------------------------------------------
  monitor:
    runs-on: ubuntu-latest
    needs: [colours, switch]
    steps:
      - uses: azure/k8s-set-context@v4
        with: { kubeconfig: '${{ secrets.KUBECONFIG }}' }

      - name: Watch the error rate for 5 minutes
        id: monitoring
        run: |
          BASE=https://bibliotech.nexussoftware.com
          ERROR_THRESHOLD=0.02         # 2% of 5xx

          for i in $(seq 1 10); do
            sleep 30

            TOTAL=$(curl -fsS "$BASE/actuator/metrics/http.server.requests" \
                    | jq '.measurements[] | select(.statistic=="COUNT") | .value')
            ERRORS=$(curl -fsS "$BASE/actuator/metrics/http.server.requests?tag=outcome:SERVER_ERROR" \
                     | jq '.measurements[] | select(.statistic=="COUNT") | .value // 0')

            RATE=$(echo "scale=4; $ERRORS / ($TOTAL + 1)" | bc)
            echo "Check $i/10 — total=$TOTAL errors=$ERRORS rate=$RATE"

            if (( $(echo "$RATE > $ERROR_THRESHOLD" | bc -l) )); then
              echo "::error::Error rate $RATE above the threshold $ERROR_THRESHOLD"
              exit 1
            fi

            if ! curl -fsS "$BASE/actuator/health/readiness" | jq -e '.status == "UP"' > /dev/null; then
              echo "::error::The readiness probe is failing"
              exit 1
            fi
          done
          echo "Monitoring passed"

      - name: Automatic ROLLBACK
        if: failure()
        run: |
          echo "::warning::Going back to colour ${{ needs.colours.outputs.active }}"
          # The rollback is INSTANT: the previous colour is still on and healthy
          kubectl patch service bibliotech -n $NAMESPACE \
            -p '{"spec":{"selector":{"app":"bibliotech","colour":"${{ needs.colours.outputs.active }}"}}}'

          curl -X POST "${{ secrets.TEAM_WEBHOOK }}" \
            -H 'Content-Type: application/json' \
            -d '{"text":"🔴 BiblioTech ${{ github.ref_name }}: automatic rollback to ${{ needs.colours.outputs.active }}"}'
          exit 1

  # ---------------------------------------------------------------
  # 6. Retire the old colour, one hour later
  # ---------------------------------------------------------------
  retire-old:
    runs-on: ubuntu-latest
    needs: [colours, monitor]
    steps:
      - uses: azure/k8s-set-context@v4
        with: { kubeconfig: '${{ secrets.KUBECONFIG }}' }

      - name: Wait an hour before retiring
        run: sleep 3600      # safety window: instant rollback available for 1 hour

      - name: Scale the old colour down to zero replicas
        run: |
          # The Deployment is not DELETED: it is scaled to 0.
          # That way the manifest survives and bringing it back is one command.
          kubectl scale deployment/bibliotech-${{ needs.colours.outputs.active }} \
            --replicas=0 -n $NAMESPACE

          curl -X POST "${{ secrets.TEAM_WEBHOOK }}" \
            -H 'Content-Type: application/json' \
            -d '{"text":"✅ BiblioTech ${{ github.ref_name }} stable. Colour ${{ needs.colours.outputs.active }} retired."}'