feat(api): add healthcheck endpoint for monitoring health from Docker/Podman (#2024)

README.md

@@ -257,6 +257,12 @@ services:
       - ./data:/app/data
       - ./books:/books
       - ./bookdrop:/bookdrop
+    healthcheck:
+      test: wget -q -O - http://localhost:${BOOKLORE_PORT}/api/v1/healthcheck
+      interval: 60s
+      retries: 5
+      start_period: 60s
+      timeout: 10s
     restart: unless-stopped
 
   mariadb:

booklore-api/src/main/java/com/adityachandel/booklore/config/security/SecurityConfig.java

@@ -50,7 +50,8 @@ public class SecurityConfig {
             "/kobo/**",                // Kobo API requests (auth handled in KoboAuthFilter)
             "/api/v1/auth/**",         // Login and token refresh endpoints (must remain public)
             "/api/v1/public-settings", // Public endpoint for checking OIDC or other app settings
-            "/api/v1/setup/**"         // Setup wizard endpoints (must remain accessible before initial setup)
+            "/api/v1/setup/**",        // Setup wizard endpoints (must remain accessible before initial setup)
+            "/api/v1/healthcheck/**"   // Healthcheck endpoints (must remain accessible for Docker healthchecks)
     };
 
     private static final String[] COMMON_UNAUTHENTICATED_ENDPOINTS = {

booklore-api/src/main/java/com/adityachandel/booklore/controller/HealthcheckController.java

@@ -0,0 +1,22 @@
+package com.adityachandel.booklore.controller;
+
+import com.adityachandel.booklore.model.dto.response.SuccessResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+
+@RestController
+@RequestMapping("/api/v1/healthcheck")
+@Tag(name = "Healthcheck", description = "Endpoints for checking the healch of the application")
+public class HealthcheckController {
+
+  @Operation(summary = "Get a ping response", description = "Check if the application is responding to requests")
+  @ApiResponse(responseCode = "200", description = "Health status returned successfully")
+  @GetMapping
+  public ResponseEntity<?> getPing() {
+    return ResponseEntity.ok(new SuccessResponse<>(200, "Pong"));
+  }
+}

example-docker/docker-compose.yml

@@ -26,6 +26,12 @@ services:
       - ./data:/app/data       # Application data (settings, metadata, cache, etc.). Persist this folder to retain your library state across container restarts.
       - ./books:/books         # Primary book library folder. Mount your collection here so BookLore can access and organize your books.
       - ./bookdrop:/bookdrop   # BookDrop folder. Files placed here are automatically detected and prepared for import.
+    healthcheck:
+      test: wget -q -O - http://localhost:6060/api/v1/healthcheck
+      interval: 60s
+      retries: 5
+      start_period: 60s
+      timeout: 10s
     restart: unless-stopped
 
   mariadb:

example-podman/booklore.container

@@ -21,3 +21,9 @@ Secret=booklore_db_pass,type=env,target=DATABASE_PASSWORD
 Environment=DATABASE_URL=jdbc:mariadb://localhost:3306/booklore
 Environment=DATABASE_USERNAME=booklore
 Environment=BOOKLORE_PORT=6060
+
+HealthCmd=wget -q -O - http://localhost:6060/api/v1/healthcheck
+HealthInterval=1m
+HealthRetries=5
+HealthStartPeriod=1m
+HealthTimeout=10s