Merge pull request #1433 from booklore-app/develop

Merge develop into master for release

Author: acx10

.gitattributes

@@ -0,0 +1,107 @@
+## Set Git attributes for paths including line ending
+## normalization, diff behavior, etc.
+##
+## Get latest from `dotnet new gitattributes`
+
+# Auto detect text files and perform LF normalization
+* text=auto
+
+#
+# The above will handle all files NOT found below
+#
+
+*.cs     text diff=csharp
+*.cshtml text diff=html
+*.csx    text diff=csharp
+*.sln    text eol=crlf
+
+# Content below from: https://github.com/gitattributes/gitattributes/blob/master/Common.gitattributes
+
+# Documents
+*.bibtex   text diff=bibtex
+*.doc      diff=astextplain
+*.DOC      diff=astextplain
+*.docx     diff=astextplain
+*.DOCX     diff=astextplain
+*.dot      diff=astextplain
+*.DOT      diff=astextplain
+*.pdf      diff=astextplain
+*.PDF      diff=astextplain
+*.rtf      diff=astextplain
+*.RTF      diff=astextplain
+*.md       text diff=markdown
+*.mdx      text diff=markdown
+*.tex      text diff=tex
+*.adoc     text
+*.textile  text
+*.mustache text
+# Per RFC 4180, .csv should be CRLF
+*.csv      text eol=crlf
+*.tab      text
+*.tsv      text
+*.txt      text
+*.sql      text
+*.epub     diff=astextplain
+
+# Graphics
+*.png      binary
+*.jpg      binary
+*.jpeg     binary
+*.gif      binary
+*.tif      binary
+*.tiff     binary
+*.ico      binary
+# SVG treated as text by default.
+*.svg      text
+# If you want to treat it as binary,
+# use the following line instead.
+# *.svg    binary
+*.eps      binary
+
+# Scripts
+# Force Unix scripts to always use lf line endings so that if a repo is accessed
+# in Unix via a file share from Windows, the scripts will work
+*.bash     text eol=lf
+*.fish     text eol=lf
+*.ksh      text eol=lf
+*.sh       text eol=lf
+*.zsh      text eol=lf
+# Likewise, force cmd and batch scripts to always use crlf
+*.bat      text eol=crlf
+*.cmd      text eol=crlf
+
+# Serialization
+*.json     text
+*.toml     text
+*.xml      text
+*.yaml     text
+*.yml      text
+
+# Archives
+*.7z       binary
+*.bz       binary
+*.bz2      binary
+*.bzip2    binary
+*.gz       binary
+*.lz       binary
+*.lzma     binary
+*.rar      binary
+*.tar      binary
+*.taz      binary
+*.tbz      binary
+*.tbz2     binary
+*.tgz      binary
+*.tlz      binary
+*.txz      binary
+*.xz       binary
+*.Z        binary
+*.zip      binary
+*.zst      binary
+
+# Text files where line endings should be preserved
+*.patch    -text
+
+# Exclude files from exporting
+.gitattributes export-ignore
+.gitignore     export-ignore
+.gitkeep       export-ignore

README.md

@@ -91,54 +91,70 @@ Ensure you have [Docker](https://docs.docker.com/get-docker/) and [Docker Compos
 
 > **Note:** Legacy images under `https://ghcr.io/adityachandelgit/booklore-app` will remain available but will not receive new updates.
 
-### 2️⃣ Create docker-compose.yml
+### 2️⃣ Set Up Your docker-compose.yml Configuration
 
-> ⚠️ If you intend to run the container as a non-root user, you must manually create all of your `/your/local/path/to/booklore` directories with read and write permissions for your intended user **before first run**.
+**Step 1: Create a `.env` file** in the same directory as your `docker-compose.yml`:
 
-Create a `docker-compose.yml` file with content:
+```ini
+# BookLore Application Settings
+APP_USER_ID=0
+APP_GROUP_ID=0
+TZ=Etc/UTC
+BOOKLORE_PORT=6060
+
+# Database Connection (BookLore)
+DATABASE_URL=jdbc:mariadb://mariadb:3306/booklore
+DB_USER=booklore
+DB_PASSWORD=ChangeMe_BookLoreApp_2025!
+
+# MariaDB Container Settings
+DB_USER_ID=1000
+DB_GROUP_ID=1000
+MYSQL_ROOT_PASSWORD=ChangeMe_MariaDBRoot_2025!
+MYSQL_DATABASE=booklore
+```
+
+**Step 2: Create a `docker-compose.yml` file** that references the `.env` variables:
 
 ```yaml
 services:
   booklore:
-    # Official Docker Hub image:
     image: booklore/booklore:latest
-    # Or the GHCR image:
+    # Alternative: Use GitHub Container Registry
     # image: ghcr.io/booklore-app/booklore:latest
     container_name: booklore
     environment:
-      - USER_ID=0
-      - GROUP_ID=0
-      - TZ=Etc/UTC
-      - DATABASE_URL=jdbc:mariadb://mariadb:3306/booklore
-      - DATABASE_USERNAME=booklore                          # Must match MYSQL_USER defined in the mariadb container
-      - DATABASE_PASSWORD=your_secure_password              
-      - BOOKLORE_PORT=6060                                  # Port BookLore listens on inside the container; must match container port below
+      - USER_ID=${APP_USER_ID}
+      - GROUP_ID=${APP_GROUP_ID}
+      - TZ=${TZ}
+      - DATABASE_URL=${DATABASE_URL}
+      - DATABASE_USERNAME=${DB_USER}
+      - DATABASE_PASSWORD=${DB_PASSWORD}
+      - BOOKLORE_PORT=${BOOKLORE_PORT}
     depends_on:
       mariadb:
         condition: service_healthy
     ports:
-      - "6060:6060" # HostPort:ContainerPort → Keep both numbers the same, and also ensure the container port matches BOOKLORE_PORT, no exceptions. 
-      # All three (host port, container port, BOOKLORE_PORT) must be identical for BookLore to function properly.
-      # Example: To expose on host port 7070, set BOOKLORE_PORT=7070 and use "7070:7070". 
+      - "${BOOKLORE_PORT}:${BOOKLORE_PORT}"
     volumes:
-      - /your/local/path/to/booklore/data:/app/data       # Application data (settings, metadata, cache, etc.). Persist this folder to retain your library state across container restarts.
-      - /your/local/path/to/booklore/books:/books         # Primary book library folder. Mount your collection here so BookLore can access and organize your books.
-      - /your/local/path/to/booklore/bookdrop:/bookdrop   # BookDrop folder. Files placed here are automatically detected and prepared for import.
+      - ./data:/app/data
+      - ./books:/books
+      - ./bookdrop:/bookdrop
     restart: unless-stopped
 
   mariadb:
     image: lscr.io/linuxserver/mariadb:11.4.5
     container_name: mariadb
     environment:
-      - PUID=1000
-      - PGID=1000
-      - TZ=Etc/UTC
-      - MYSQL_ROOT_PASSWORD=super_secure_password  # Use a strong password for the database's root user, should be different from MYSQL_PASSWORD
-      - MYSQL_DATABASE=booklore
-      - MYSQL_USER=booklore                        # Must match DATABASE_USERNAME defined in the booklore container
-      - MYSQL_PASSWORD=your_secure_password        # Use a strong password; must match DATABASE_PASSWORD defined in the booklore container
+      - PUID=${DB_USER_ID}
+      - PGID=${DB_GROUP_ID}
+      - TZ=${TZ}
+      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
+      - MYSQL_DATABASE=${MYSQL_DATABASE}
+      - MYSQL_USER=${DB_USER}
+      - MYSQL_PASSWORD=${DB_PASSWORD}
     volumes:
-      - /your/local/path/to/mariadb/config:/config
+      - ./mariadb/config:/config
     restart: unless-stopped
     healthcheck:
       test: [ "CMD", "mariadb-admin", "ping", "-h", "localhost" ]
@@ -147,9 +163,6 @@ services:
       retries: 10
 ```
 
-Note: You can find the latest BookLore image tag `BOOKLORE_IMAGE_TAG` (e.g. v.0.x.x) from the Releases section:
-📦 [Latest Image Tag – GitHub Releases](https://github.com/adityachandelgit/BookLore/releases)
-
 ### 3️⃣ Start the Containers
 
 Run the following command to start the services:
@@ -163,37 +176,9 @@ docker compose up -d
 Once the containers are up, access BookLore in your browser at:
 
 ```ini
-http : //localhost:6060
+http://localhost:6060
 ```
 
-## ⚙️ Supported Environment Variables
-
-### BookLore Container
-
-| Key                  | Default Value                          | Description                                                                                                                                                                                                                                                        |
-|----------------------|----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `USER_ID`            | `0`                                    | User ID for file ownership within the container. Set this to match your host user's UID if running as non-root (e.g., `1000`). Use `id -u` on Linux to find your UID.                                                                                              |
-| `GROUP_ID`           | `0`                                    | Group ID for file ownership within the container. Set this to match your host user's GID if running as non-root (e.g., `1000`). Use `id -g` on Linux to find your GID.                                                                                             |
-| `TZ`                 | `Etc/UTC`                              | Timezone for the application. Controls timestamps in logs and UI. Use standard timezone identifiers (e.g., `America/New_York`, `Europe/London`, `Asia/Tokyo`). See [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). |
-| `DATABASE_URL`       | `jdbc:mariadb://mariadb:3306/booklore` | JDBC connection string for MariaDB/MySQL database. Format: `jdbc:mariadb://hostname:port/database_name`. Only modify if using a custom database host, port, or external database server.                                                                           |
-| `DATABASE_USERNAME`  | `booklore`                             | Username for database authentication. Must match `MYSQL_USER` in your MariaDB container configuration.                                                                                                                                                             |
-| `DATABASE_PASSWORD`  | -                                      | Password for database authentication. **Required**. Use a strong, unique password. Must match `MYSQL_PASSWORD` in your MariaDB container configuration. Store securely and never commit to version control.                                                        |
-| `BOOKLORE_PORT`      | `6060`                                 | Internal port BookLore listens on. **Critical**: This must match both the host and container ports in your port mapping (e.g., `6060:6060`). Changing this requires updating all three values. Example: For port `7070`, use `BOOKLORE_PORT=7070` and `7070:7070`. |
-| `SWAGGER_ENABLED`    | `false`                                | Controls access to Swagger UI for API documentation and testing. Set to `true` to enable at `/swagger-ui.html` (useful for development/testing). Keep `false` in production for security.                                                                          |
-| `FORCE_DISABLE_OIDC` | `false`                                | Forces local username/password authentication only. Set to `true` to completely disable OIDC/OAuth2 providers (Authentik, Pocket ID, etc.). Useful for troubleshooting authentication issues or temporarily bypassing external identity providers.                 |
-
-### MariaDB Container
-
-| Key                   | Default Value | Description                                                                                                                                                                                                      |
-|-----------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `PUID`                | `1000`        | Process User ID for the LinuxServer.io MariaDB container. Set this to match your host user's UID for proper file permissions. Use `id -u` on Linux to find your UID.                                            |
-| `PGID`                | `1000`        | Process Group ID for the LinuxServer.io MariaDB container. Set this to match your host user's GID for proper file permissions. Use `id -g` on Linux to find your GID.                                           |
-| `TZ`                  | `Etc/UTC`     | Timezone for the MariaDB container. Should match the BookLore container's timezone for consistency in timestamps.                                                                                                |
-| `MYSQL_ROOT_PASSWORD` | -             | Root password for the MariaDB database. **Required**. Use a strong, unique password different from `MYSQL_PASSWORD`. This provides administrative access to the database server. Never expose or commit to VCS. |
-| `MYSQL_DATABASE`      | `booklore`    | Name of the database to create on first run. This database will be used by BookLore to store all application data. Should not be changed after initial setup.                                                   |
-| `MYSQL_USER`          | `booklore`    | Username for the application database user. Must match `DATABASE_USERNAME` in the BookLore container configuration. This user will have full access to the `MYSQL_DATABASE`.                                     |
-| `MYSQL_PASSWORD`      | -             | Password for the application database user. **Required**. Use a strong, unique password. Must match `DATABASE_PASSWORD` in the BookLore container configuration. Store securely and never commit to VCS.         |
-
 ## 📥 Bookdrop Folder: Auto-Import Files
 
 BookLore now supports a **Bookdrop folder**, a special directory where you can drop your book files (`.pdf`, `.epub`, `.cbz`, etc.), and BookLore will automatically detect, process, and prepare them for import. This makes it easy to bulk add new books without manually uploading each one.
@@ -214,9 +199,9 @@ services:
   booklore:
     ...
     volumes:
-      - /your/local/path/to/booklore/data:/app/data
-      - /your/local/path/to/booklore/books:/books
-      - /your/local/path/to/booklore/bookdrop:/bookdrop # 👈 Bookdrop directory
+      - ./data:/app/data
+      - ./books:/books
+      - ./bookdrop:/bookdrop # 👈 Bookdrop directory
 ```
 
 ## 🔑 OIDC/OAuth2 Authentication (Authentik, Pocket ID, etc.)

booklore-api/src/main/java/com/adityachandel/booklore/config/OpenApiConfig.java

@@ -2,9 +2,12 @@
 
 import io.swagger.v3.oas.models.Components;
 import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Contact;
 import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.info.License;
 import io.swagger.v3.oas.models.security.SecurityRequirement;
 import io.swagger.v3.oas.models.security.SecurityScheme;
+import io.swagger.v3.oas.models.servers.Server;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
@@ -16,7 +19,18 @@ public OpenAPI customOpenAPI() {
         final String securitySchemeName = "bearerAuth";
 
         return new OpenAPI()
-                .info(new Info().title("Booklore API").version("1.0"))
+                .info(new Info()
+                        .title("Booklore API")
+                        .version("1.0")
+                        .description("Booklore is a personal library management system. This API allows you to manage books, libraries, users, shelves, and more.")
+                        .contact(new Contact()
+                                .name("Booklore")
+                                .url("https://github.com/booklore-app/booklore"))
+                        .license(new License()
+                                .name("GNU General Public License v3.0")
+                                .url("https://www.gnu.org/licenses/gpl-3.0.html"))
+                )
+                .addServersItem(new Server().url("/").description("Current server"))
                 .addSecurityItem(new SecurityRequirement().addList(securitySchemeName))
                 .components(new Components().addSecuritySchemes(securitySchemeName,
                         new SecurityScheme()

booklore-api/src/main/java/com/adityachandel/booklore/config/TaskSchedulerConfig.java

@@ -0,0 +1,24 @@
+package com.adityachandel.booklore.config;
+
+import com.adityachandel.booklore.service.task.TaskService;
+import lombok.AllArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.boot.context.event.ApplicationReadyEvent;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.event.EventListener;
+import org.springframework.scheduling.annotation.EnableScheduling;
+
+@Configuration
+@EnableScheduling
+@AllArgsConstructor
+@Slf4j
+public class TaskSchedulerConfig {
+
+    private final TaskService taskService;
+
+    @EventListener(ApplicationReadyEvent.class)
+    public void initializeScheduledTasks() {
+        log.info("Application ready, initializing scheduled tasks");
+        taskService.initializeScheduledTasks();
+    }
+}

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

@@ -4,20 +4,21 @@
 import org.springframework.boot.web.servlet.FilterRegistrationBean;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.core.Ordered;
 
 @Configuration
 public class ImageCacheConfig {
 
     @Bean
-    public FilterRegistrationBean<ImageCachingFilter> imageCachingFilterRegistration(ImageCachingFilter filter) {
+    public FilterRegistrationBean<ImageCachingFilter> imageCachingFilterRegistration() {
         FilterRegistrationBean<ImageCachingFilter> registrationBean = new FilterRegistrationBean<>();
-        registrationBean.setFilter(filter);
+        registrationBean.setFilter(new ImageCachingFilter());
         registrationBean.addUrlPatterns(
                 "/api/v1/media/book/*/cover",
                 "/api/v1/media/book/*/thumbnail",
                 "/api/v1/media/book/*/backup-cover"
         );
-        registrationBean.setOrder(1);
+        registrationBean.setOrder(Ordered.LOWEST_PRECEDENCE);
         return registrationBean;
     }
 }

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

@@ -17,6 +17,7 @@
 import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
 import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
+import org.springframework.security.config.annotation.web.configurers.HeadersConfigurer;
 import org.springframework.security.config.http.SessionCreationPolicy;
 import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
 import org.springframework.security.crypto.password.PasswordEncoder;
@@ -42,9 +43,9 @@ public class SecurityConfig {
     private final AppProperties appProperties;
 
     private static final String[] SWAGGER_ENDPOINTS = {
-            "/swagger-ui.html",
-            "/swagger-ui/**",
-            "/v3/api-docs/**"
+            "/api/v1/swagger-ui.html",
+            "/api/v1/swagger-ui/**",
+            "/api/v1/api-docs/**"
     };
 
     private static final String[] COMMON_PUBLIC_ENDPOINTS = {
@@ -120,6 +121,9 @@ public SecurityFilterChain coverJwtApiSecurityChain(HttpSecurity http, CoverJwtF
                 .securityMatcher("/api/v1/media/**")
                 .csrf(AbstractHttpConfigurer::disable)
                 .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+                .headers(headers -> headers
+                        .cacheControl(HeadersConfigurer.CacheControlConfig::disable)
+                )
                 .authorizeHttpRequests(auth -> auth
                         .anyRequest().permitAll()
                 )
@@ -148,7 +152,6 @@ public SecurityFilterChain jwtApiSecurityChain(HttpSecurity http) throws Excepti
         return http.build();
     }
 
-
     @Bean
     public AuthenticationManager authenticationManager(HttpSecurity http) throws Exception {
         return http.getSharedObject(AuthenticationManagerBuilder.class)