### Start Docker Development Stack with Justfile

Source: https://github.com/grimmory-tools/grimmory/blob/develop/DEVELOPMENT.md

Bring up the complete Docker development environment, including the frontend, backend, and database, using 'just dev-up'. This is the recommended setup method.

```bash
just dev-up
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/grimmory-tools/grimmory/blob/develop/DEVELOPMENT.md

Installs the necessary dependencies for the frontend application using 'just ui install'. This is a prerequisite for running the frontend development server.

```bash
just ui install
```

--------------------------------

### Start Grimmory Pod

Source: https://github.com/grimmory-tools/grimmory/blob/develop/deploy/podman/quadlet/README.md

Start the Grimmory pod using systemctl. This command initiates the containers defined in the Quadlet files.

```bash
systemctl --user start grimmory-pod.service
```

--------------------------------

### Install Frontend Dependencies with Justfile

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/DEVELOPMENT.md

Installs or updates dependencies for local development. Use 'install-ci' for an exact replica of the CI environment.

```bash
just install		# Install or update dependencies for local development
```

```bash
just install-ci		# Install dependencies exactly as CI does
```

--------------------------------

### Start Backend Locally

Source: https://github.com/grimmory-tools/grimmory/blob/develop/backend/DEVELOPMENT.md

Navigate to the backend directory and use `just run` to start the backend. A MariaDB instance and appropriate configuration are expected.

```bash
cd backend
just run
```

--------------------------------

### Start Backend with Specific Spring Profile

Source: https://github.com/grimmory-tools/grimmory/blob/develop/backend/DEVELOPMENT.md

To start the backend with a profile other than the default, specify the profile using the `profile=` argument.

```bash
just run profile=local
```

--------------------------------

### Local Frontend Development Setup

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/DEVELOPMENT.md

Steps to set up and run the frontend development environment locally. Assumes you are in the 'frontend' directory.

```bash
cd frontend
just install
just dev
```

--------------------------------

### Start Local Frontend Development Server

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/DEVELOPMENT.md

Starts the local development server for the frontend application. The default address is http://localhost:4200.

```bash
just dev			# Start the local dev server
```

--------------------------------

### Start Angular Development Server

Source: https://github.com/grimmory-tools/grimmory/blob/develop/CLAUDE.md

Start the Angular development server for the frontend. This command is used for local frontend development.

```bash
just ui dev
```

--------------------------------

### Start Spring Boot Application

Source: https://github.com/grimmory-tools/grimmory/blob/develop/CLAUDE.md

Start the Spring Boot application with the development profile enabled. This is for local backend development.

```bash
just api run
```

--------------------------------

### Start Angular Development Server

Source: https://github.com/grimmory-tools/grimmory/blob/develop/AGENTS.md

Starts the Angular development server for the frontend application. Use this for local frontend development and testing.

```bash
just ui dev         # start the Angular dev server
```

--------------------------------

### Start Spring Boot Development Server

Source: https://github.com/grimmory-tools/grimmory/blob/develop/AGENTS.md

Starts the Spring Boot application with the development profile enabled. Use this for local backend development and testing.

```bash
just api run        # start Spring Boot with the dev profile
```

--------------------------------

### Full Docker Compose Configuration

Source: https://github.com/grimmory-tools/grimmory/blob/develop/README.md

A comprehensive Docker Compose setup for Grimmory and its MariaDB dependency. Configure environment variables in a `.env` file. The `healthcheck` ensures services start in the correct order.

```yaml
services:
  grimmory:
    image: grimmory/grimmory:latest
    # Convenience tag:
    # image: grimmory/grimmory:<release-version>
    # Alternative: ghcr.io/grimmory-tools/grimmory:<release-version>
    # To build from source instead: comment out 'image' and uncomment below
    # build: .
    container_name: grimmory
    environment:
      - USER_ID=${APP_USER_ID}
      - GROUP_ID=${APP_GROUP_ID}
      - TZ=${TZ}
      - DATABASE_URL=${DATABASE_URL}
      - DATABASE_USERNAME=${DB_USER}
      - DATABASE_PASSWORD=${DB_PASSWORD}
      - API_DOCS_ENABLED=${API_DOCS_ENABLED}
      - DISK_TYPE=${DISK_TYPE}
    depends_on:
      mariadb:
        condition: service_healthy
    ports:
      - "6060:6060"
    volumes:
      - ./data:/app/data
      - ./books:/books
      - ./bookdrop:/bookdrop
    healthcheck:
      test: wget -q -O - http://localhost:6060/api/v1/healthcheck
      interval: 60s
      retries: 5
      start_period: 60s
      timeout: 10s
    restart: unless-stopped

  mariadb:
    image: lscr.io/linuxserver/mariadb:11.4.5
    environment:
      - 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:
      - ./mariadb/config:/config
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "mariadb-admin", "ping", "-h", "localhost"]
      interval: 5s
      timeout: 5s
      retries: 10
```

--------------------------------

### Basic File Naming Pattern Example

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/settings/file-naming-pattern/file-naming-pattern.component.html

Demonstrates a simple file naming pattern using author and title placeholders. This is a common pattern for organizing files.

```plaintext
`{{ '{authors} - {title}' }}` `Patrick Rothfuss - The Name of the Wind.epub`
```

--------------------------------

### Docker Compose for Forward Auth Configuration

Source: https://github.com/grimmory-tools/grimmory/blob/develop/docs/forward-auth-with-proxy.md

Integrate Grimmory into your Docker Compose setup with forward authentication enabled. This example demonstrates setting the necessary environment variables for remote user authentication, including custom header names and admin group configuration.

```yaml
services:
  grimmory:
    image: ghcr.io/grimmory-tools/grimmory:v0.38.2
    environment:
      # Forward Auth Configuration
      - REMOTE_AUTH_ENABLED=true
      - REMOTE_AUTH_CREATE_NEW_USERS=true
      - REMOTE_AUTH_HEADER_NAME=Remote-Name
      - REMOTE_AUTH_HEADER_USER=Remote-User
      - REMOTE_AUTH_HEADER_EMAIL=Remote-Email
      - REMOTE_AUTH_HEADER_GROUPS=Remote-Groups
      - REMOTE_AUTH_ADMIN_GROUP=admin
      # - REMOTE_AUTH_GROUPS_DELIMITER=\\s*,\\s*  # Uncomment if your proxy sends comma-separated groups
    # ... rest of configuration ...
```

--------------------------------

### Launch Grimmory with Docker Compose

Source: https://github.com/grimmory-tools/grimmory/blob/develop/README.md

Command to start all services defined in your `docker-compose.yml` file in detached mode.

```bash
docker compose up -d
```

--------------------------------

### BookDrop Volume Mount

Source: https://github.com/grimmory-tools/grimmory/blob/develop/README.md

Example of mounting the `./bookdrop` directory from the host to the container's `/bookdrop` path for the BookDrop feature.

```yaml
volumes:
  - ./bookdrop:/bookdrop
```

--------------------------------

### Create Grimmory Database and User

Source: https://github.com/grimmory-tools/grimmory/blob/develop/DEVELOPMENT.md

SQL commands to create the 'grimmory' database, a dedicated user 'grimmory_user', and grant necessary privileges. This is part of the manual backend setup.

```sql
CREATE DATABASE IF NOT EXISTS grimmory;
CREATE USER 'grimmory_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON grimmory.* TO 'grimmory_user'@'localhost';
FLUSH PRIVILEGES;
```

--------------------------------

### Initial Modifier Example

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/settings/file-naming-pattern/file-naming-pattern.component.html

Use the initial modifier to create a folder structure based on the first letter of the author's last name. Example: '{authors:initial}/{authors:sort}/{title}'.

```text
{authors:initial}/{authors:sort}/{title}
```

--------------------------------

### Letter Folder Modifier Example

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/settings/file-naming-pattern/file-naming-pattern.component.html

Use the initial modifier for the title to create a folder based on the first letter of the title. Example: '{title:initial}/{authors}/{title}'.

```text
{title:initial}/{authors}/{title}
```

--------------------------------

### Komga API Clean Mode Usage Examples

Source: https://github.com/grimmory-tools/grimmory/blob/develop/docs/komga-clean-mode.md

Demonstrates how to use the `clean` query parameter with Komga API endpoints. It can be used without a value or with an explicit `true` value.

```http
GET /komga/api/v1/series?clean
GET /komga/api/v1/books/123?clean
GET /komga/api/v1/libraries?clean
```

```http
GET /komga/api/v1/series?clean=true
GET /komga/api/v1/books/123?clean=true
GET /komga/api/v1/libraries?clean=true
```

--------------------------------

### Stricter CI Dependency and Audit Flow

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/DEVELOPMENT.md

Use these commands to mirror the stricter CI dependency policy and audit flow from a clean install.

```bash
just install-ci
just ci-check
```

--------------------------------

### Local Validation Before PR

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/DEVELOPMENT.md

Run frontend checks locally before submitting a Pull Request. Includes installing dependencies and running the check command.

```bash
just install
just check
```

--------------------------------

### Caddyfile for Authelia Forward Auth

Source: https://github.com/grimmory-tools/grimmory/blob/develop/docs/forward-auth-with-proxy.md

Configure Caddy as a reverse proxy to use Authelia for forward authentication. This setup directs authentication requests to Authelia and forwards authorized requests to Grimmory, copying specified headers.

```caddyfile
books.example.com {
  forward_auth authelia:9091 {
    uri /api/authz/forward-auth
    copy_headers Remote-User Remote-Name Remote-Email Remote-Groups
  }

  reverse_proxy grimmory:6060
}
```

--------------------------------

### Komga API Clean Mode Response Example

Source: https://github.com/grimmory-tools/grimmory/blob/develop/docs/komga-clean-mode.md

Illustrates a Komga API JSON response when the `clean` parameter is active. Lock fields, null values, and empty collections are excluded.

```json
{
  "title": "My Book"
}
```

--------------------------------

### Komga API Default Response Example

Source: https://github.com/grimmory-tools/grimmory/blob/develop/docs/komga-clean-mode.md

Shows a typical Komga API JSON response without the `clean` parameter enabled. This includes lock fields, empty strings, and empty arrays.

```json
{
  "title": "My Book",
  "titleLock": false,
  "summary": "",
  "summaryLock": false,
  "language": "en",
  "languageLock": false,
  "publisher": "",
  "publisherLock": false,
  "genres": [],
  "genresLock": false,
  "tags": [],
  "tagsLock": false
}
```

--------------------------------

### Lower Case Modifier Example

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/settings/file-naming-pattern/file-naming-pattern.component.html

Use the lower modifier to convert the title to lowercase. Example: '{title:lower}'.

```text
{title:lower}
```

--------------------------------

### Upper Case Modifier Example

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/settings/file-naming-pattern/file-naming-pattern.component.html

Use the upper modifier to convert the title to uppercase. Example: '{title:upper}'.

```text
{title:upper}
```

--------------------------------

### List Frontend Recipes with Justfile

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/DEVELOPMENT.md

Use this command to list all available frontend recipes defined in the Justfile. This helps in understanding the available development tasks.

```bash
just			# List frontend recipes
```

--------------------------------

### Access Frontend Recipes via Repository Root

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/DEVELOPMENT.md

These commands show how to run the same frontend 'just' recipes from the repository root using the 'ui' namespace.

```bash
just ui install
```

```bash
just ui install-ci
```

```bash
just ui dev
```

```bash
just ui test
```

```bash
just ui coverage
```

```bash
just ui check
```

```bash
just ui lint
```

--------------------------------

### Build and Test Commands

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/DEVELOPMENT.md

Common commands for building the production bundle, running tests, and performing verification checks for the frontend.

```bash
just build
just test
just coverage
just check
just lint
```

--------------------------------

### Show All Recipes with Justfile

Source: https://github.com/grimmory-tools/grimmory/blob/develop/DEVELOPMENT.md

Use this command to display all available recipes in the root, API, and UI Justfiles. This is useful for understanding the available automation scripts.

```bash
just
```

--------------------------------

### Combined Modifiers Example

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/settings/file-naming-pattern/file-naming-pattern.component.html

Combine multiple modifiers for a complex file naming pattern. Example: '{authors:sort} - {title:lower}'.

```text
{authors:sort} - {title:lower}
```

--------------------------------

### List Backend Recipes with Justfile

Source: https://github.com/grimmory-tools/grimmory/blob/develop/backend/DEVELOPMENT.md

Use the `just` command to list available backend recipes. This is the primary way to interact with backend development tasks.

```bash
just			# List backend recipes
just run 		# Start the backend with the dev profile
just test 		# Run backend tests
just coverage 		# Generate JaCoCo coverage output
just check 		# Run the Gradle check lifecycle
just build 		# Build the backend jar
just tasks 		# Show available Gradle tasks
```

--------------------------------

### Build Production Bundle with Justfile

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/DEVELOPMENT.md

Builds the production-ready bundle for the frontend application. The output is typically placed in 'dist/grimmory/'.

```bash
just build			# Build the production bundle
```

--------------------------------

### Sort Modifier Example

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/settings/file-naming-pattern/file-naming-pattern.component.html

Use the sort modifier to order files by author's last name. Example: '{authors:sort}/{title}'.

```text
{authors:sort}/{title}
```

--------------------------------

### First Name Modifier Example

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/settings/file-naming-pattern/file-naming-pattern.component.html

Use the first modifier to include the author's first name in the pattern. Example: '{authors:first}/{title}'.

```text
{authors:first}/{title}
```

--------------------------------

### Run Backend Recipes from Repository Root

Source: https://github.com/grimmory-tools/grimmory/blob/develop/backend/DEVELOPMENT.md

When running from the repository root, prepend `api` to the `just` commands to target the backend recipes.

```bash
just api run
just api test
just api coverage
just api check
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/grimmory-tools/grimmory/blob/develop/DEVELOPMENT.md

Examples of commit messages following the Conventional Commits specification. Use types like 'feat', 'fix', 'docs', etc., and include a scope and subject. Breaking changes are indicated with an exclamation mark.

```text
feat(reader): add keyboard navigation for page turning
fix(api): resolve memory leak in book scanning service
feat(auth)!: migrate to OAuth 2.1

BREAKING CHANGE: OAuth 2.0 is no longer supported
```

--------------------------------

### Build and Run Production Docker Image

Source: https://github.com/grimmory-tools/grimmory/blob/develop/DEVELOPMENT.md

Use these commands to build the production Docker image and run it locally. The first build may take longer due to dependency caching.

```bash
just image-build          # Build the image
just db-up                # Start only the database from the dev stack
just image-run            # Run the production image against it
```

```bash
just db-down    # Stop the database when done
just dev-down   # Or stop the full stack if started with `just dev-up`
```

--------------------------------

### Build and Test Backend

Source: https://github.com/grimmory-tools/grimmory/blob/develop/backend/DEVELOPMENT.md

Standard commands for building the backend artifact and running tests. These are essential for verifying code changes.

```bash
just build
just test
just coverage
just check
```

--------------------------------

### Run Backend and Frontend Verification

Source: https://github.com/grimmory-tools/grimmory/blob/develop/AGENTS.md

Execute this command to run all backend and frontend verification checks. This is a comprehensive check before committing changes.

```bash
just check          # run backend + frontend verification
```

--------------------------------

### Run Backend and Frontend Tests

Source: https://github.com/grimmory-tools/grimmory/blob/develop/AGENTS.md

Execute this command to run all backend and frontend tests. This is a comprehensive test suite execution.

```bash
just test           # run backend + frontend tests
```

--------------------------------

### Run Frontend Tests with Justfile

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/DEVELOPMENT.md

Executes frontend unit tests. Use 'coverage' to generate a test coverage report.

```bash
just test			# Run frontend tests
```

```bash
just coverage		# Run tests with coverage output
```

--------------------------------

### Lint Frontend Code with Justfile

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/DEVELOPMENT.md

Runs the frontend linter to check for code style and potential issues.

```bash
just lint			# Run the frontend linter
```

--------------------------------

### Translation Key for ASIN Label

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/author-browser/components/author-editor/author-editor.component.html

Displays a translated string for the ASIN label. Verify that the translation key 'asinLabel' exists in your internationalization setup.

```HTML
{{ t('asinLabel') }}
```

--------------------------------

### Run Backend and Frontend Tests

Source: https://github.com/grimmory-tools/grimmory/blob/develop/CLAUDE.md

Execute all backend and frontend tests. This command is a repository-level test suite execution.

```bash
just test
```

--------------------------------

### Generate Library Preview

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/settings/file-naming-pattern/file-naming-pattern.component.html

Generates a preview of the file naming pattern for a specific library, showing custom or default patterns in action.

```html
`{{ generateLibraryPreview(library) }}`
```

--------------------------------

### File Naming Pattern with Absolute Path

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/settings/file-naming-pattern/file-naming-pattern.component.html

Specifies an absolute path for file organization, starting from the root directory. This pattern is useful for creating a fixed directory structure.

```plaintext
`{{ '/{authors}/{title}' }}` `/Patrick Rothfuss/The Name of the Wind.epub`
```

--------------------------------

### Root Justfile Commands

Source: https://github.com/grimmory-tools/grimmory/blob/develop/README.md

Common development commands available via the root `Justfile`. Use `just` to see all available recipes.

```bash
just               # Show root + api + ui recipes
just test          # Run backend and frontend tests
just api test      # Run backend tests only
just ui dev        # Start the frontend dev server
```

--------------------------------

### Run Backend and Frontend Verification

Source: https://github.com/grimmory-tools/grimmory/blob/develop/CLAUDE.md

Execute both backend and frontend verification checks. This command is a repository-level verification.

```bash
just check
```

--------------------------------

### Generate Default Preview

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/settings/file-naming-pattern/file-naming-pattern.component.html

Displays a preview of the default file naming pattern. This is useful for understanding the current default behavior.

```html
`{{ generateDefaultPreview() }}`
```

--------------------------------

### Render Virtualized Rows and Cover Previews

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/book/components/book-browser/book-table/book-table.component.html

This snippet demonstrates rendering virtualized rows for a book table. It includes logic for accessing book data, handling visible cells, and conditionally displaying cover previews based on URL availability.

```html
@for (virtualRow of rowVirtualizer.getVirtualItems(); track virtualRow.key) { @if (books().get(virtualRow.index); as book) { } @else {

@for (columnId of visibleCellIds(); track columnId; let columnIndex = $index) {

}

} }

@if (coverPreview(); as preview) {

@if (preview.coverUrl; as coverUrl) {  } @else { }

}
```

--------------------------------

### Enable Forward Auth Environment Variables

Source: https://github.com/grimmory-tools/grimmory/blob/develop/docs/forward-auth-with-proxy.md

Configure Grimmory to trust headers from a reverse proxy for authentication. Ensure REMOTE_AUTH_ENABLED is set to true. User creation can be automated by setting REMOTE_AUTH_CREATE_NEW_USERS to true. Define header names for user, name, email, and groups as specified by your proxy.

```bash
REMOTE_AUTH_ENABLED=true
REMOTE_AUTH_CREATE_NEW_USERS=true
REMOTE_AUTH_HEADER_USER=Remote-User
REMOTE_AUTH_HEADER_NAME=Remote-Name
REMOTE_AUTH_HEADER_EMAIL=Remote-Email
REMOTE_AUTH_HEADER_GROUPS=Remote-Groups
REMOTE_AUTH_ADMIN_GROUP=admin
REMOTE_AUTH_GROUPS_DELIMITER=\\s+
```

--------------------------------

### Build Production Docker Image Locally with Justfile

Source: https://github.com/grimmory-tools/grimmory/blob/develop/DEVELOPMENT.md

Build the production Docker image for Grimmory locally using the 'just image-build' command. This is useful for testing the final deployment artifact.

```bash
just image-build
```

--------------------------------

### Run Frontend Verification

Source: https://github.com/grimmory-tools/grimmory/blob/develop/CLAUDE.md

Execute frontend verification checks. This command targets the frontend application specifically.

```bash
just ui check
```

--------------------------------

### Run Backend Tests

Source: https://github.com/grimmory-tools/grimmory/blob/develop/CLAUDE.md

Execute backend tests. This command targets the backend services specifically.

```bash
just api test
```

--------------------------------

### Copy Quadlet Files to Systemd Directory

Source: https://github.com/grimmory-tools/grimmory/blob/develop/deploy/podman/quadlet/README.md

Copy the necessary Grimmory Quadlet files to the Podman Quadlet monitoring directory. This allows systemd to recognize and manage the containers.

```bash
mkdir -p ~/.config/containers/systemd && cp ./*grimmory* ~/.config/containers/systemd/
```

--------------------------------

### Run Frontend Verification

Source: https://github.com/grimmory-tools/grimmory/blob/develop/AGENTS.md

Execute frontend verification checks. This command is useful for ensuring frontend code quality and standards.

```bash
just ui check       # run frontend verification
```

--------------------------------

### Run All Frontend Tests

Source: https://github.com/grimmory-tools/grimmory/blob/develop/DEVELOPMENT.md

Executes all tests for the frontend application using Vitest. This command is part of the testing workflow.

```bash
just ui test
```

--------------------------------

### Conditional Rendering for Welcome Message

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/dashboard/components/main-dashboard/main-dashboard.component.html

Displays a welcome message and subtitle if the user has admin or library management permissions. Uses translation keys for content.

```html
@if (isBooksLoading()) {

} @else {

@if (isLibrariesEmpty()) {

@if (userService.currentUser()?.permissions; as permissions) {

@if (permissions.admin || permissions.canManageLibrary) {

{{ t('welcomeTitle') }}
{{ t('welcomeSubtitle') }}
====================================================

{{ t('welcomeDescription') }}

}

}

}

```

--------------------------------

### Configure Grimmory Environment Variables

Source: https://github.com/grimmory-tools/grimmory/blob/develop/README.md

This `.env` file configures application, database, and storage settings for Grimmory. Ensure sensitive information like database passwords are changed.

```ini
# Application
APP_USER_ID=1000
APP_GROUP_ID=1000
TZ=Etc/UTC

# Database
DATABASE_URL=jdbc:mariadb://mariadb:3306/grimmory
DB_USER=grimmory
DB_PASSWORD=ChangeMe_Grimmory_2025!

# Optional: enable API docs + export OpenAPI JSON (defaults to false)
API_DOCS_ENABLED=false

# Storage: LOCAL (default) or NETWORK (disables file operations; see Network Storage section)
DISK_TYPE=LOCAL

# MariaDB
DB_USER_ID=1000
DB_GROUP_ID=1000
MYSQL_ROOT_PASSWORD=ChangeMe_MariaDBRoot_2025!
MYSQ_DATABASE=grimmory
```

--------------------------------

### Enable API Docs

Source: https://github.com/grimmory-tools/grimmory/blob/develop/backend/DEVELOPMENT.md

Set `API_DOCS_ENABLED=true` for runtime or container profiles to expose OpenAPI documentation endpoints. This is controlled via `application.yaml`.

```bash
API_DOCS_ENABLED=true
```

--------------------------------

### Run Backend Tests

Source: https://github.com/grimmory-tools/grimmory/blob/develop/AGENTS.md

Execute backend-specific tests. This command is useful for focused backend testing during development.

```bash
just api test       # run backend tests
```

--------------------------------

### Cross-Platform Docker Image Build

Source: https://github.com/grimmory-tools/grimmory/blob/develop/DEVELOPMENT.md

Build the production Docker image for a specific platform like Linux ARM64. Ensure Docker is configured for cross-platform builds if necessary.

```bash
just image-build linux/arm64 grimmory:local-arm64
```

--------------------------------

### Run Backend Checks Locally Before PR

Source: https://github.com/grimmory-tools/grimmory/blob/develop/backend/DEVELOPMENT.md

Execute these commands locally to ensure the backend passes essential checks before submitting a Pull Request.

```bash
just test
just check
```

--------------------------------

### Initialize Grimmory Viewer

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/assets/embedpdf-frame.html

Initializes the Grimmory viewer with various configuration options including locales, disabled categories, annotation settings, zoom levels, and rendering quality. It also sets up event listeners for document opening, errors, and closing, as well as page changes and viewer readiness.

```javascript
const viewer = await Grimmory.init(target, {
 locale: msg.locale || 'en',
 fallbackLocale: 'en',
 }, fallbackLocale: 'en', }, disabledCategories: [ 'document-open', 'document-close', ], annotations: {
 autoCommit: true,
 autoOpenLinks: false,
 }, zoom: {
 defaultZoomLevel: 'fit-page',
 }, render: {
 defaultImageQuality: isSmallViewport ? 0.85 : 0.92
 }, tiling: isSmallViewport ? {
 tileSize: 640,
 overlapPx: 2,
 extraRings: 1
 } : {
 tileSize: 1024,
 overlapPx: 2,
 extraRings: 1
 }, }); injectGrimmoryStyles(target);
try {
 registry = await viewer.registry;
 applyLocale(registry.getPlugin('i18n')?.provides?.(), msg.locale);
 const dm = registry.getPlugin('document-manager')?.provides();
 if (dm) {
 dm.onDocumentOpened?.((ev) => {
 const pageCount = ev?.document?.pageCount ?? ev?.pageCount;
 log('Document opened, pages:', pageCount);
 parent.postMessage({ type: 'documentOpened', pageCount }, myOrigin);
 });
 dm.onDocumentError?.((ev) => {
 log('Document error:', ev);
 parent.postMessage({ type: 'documentError', error: String(ev?.message || ev) }, myOrigin);
 });
 dm.onDocumentClosed?.((ev) => {
 log('Document closed:', ev?.documentId);
 });
 }
 const scrollPlugin = registry.getPlugin('scroll')?.provides();
 if (scrollPlugin) {
 scrollPlugin.onPageChange((ev) => {
 parent.postMessage({ type: 'pageChange', pageNumber: ev.pageNumber, totalPages: ev.totalPages }, myOrigin);
 });
 }
 parent.postMessage({ type: 'ready' }, myOrigin);
 if (typeof ResizeObserver !== 'undefined') {
 const observer = new ResizeObserver(() => {
 try {
 const zoomPlugin = registry.getPlugin('zoom')?.provides();
 if (zoomPlugin) {
 const state = zoomPlugin.getState();
 if (state.zoomLevel === 'fit-page') {
 zoomPlugin.requestZoom('fit-page');
 }
 }
 } catch (_) { /* no active document yet */ }
 });
 observer.observe(target);
 }
} catch (err) {
 log('Registry error:', err);
 parent.postMessage({ type: 'documentError', error: String(err) }, myOrigin);
}

```

--------------------------------

### Run Specific Backend Test Class

Source: https://github.com/grimmory-tools/grimmory/blob/develop/DEVELOPMENT.md

Executes a specific test class within the backend. Replace 'org.booklore.service.BookServiceTest' with the desired test class name.

```bash
just api test --test_class=org.booklore.service.BookServiceTest
```

--------------------------------

### Basic Docker Compose Service

Source: https://github.com/grimmory-tools/grimmory/blob/develop/README.md

A minimal Docker Compose service definition for Grimmory. Ensure to replace `<tag>` with a specific version or use `latest`.

```yaml
services:
  booklore:
    image: grimmory/grimmory:v2.2.1
```

--------------------------------

### Export OpenAPI Specification

Source: https://github.com/grimmory-tools/grimmory/blob/develop/backend/DEVELOPMENT.md

Use this command to export a release-ready OpenAPI specification without running the full container stack.

```bash
just openapi-export
```

--------------------------------

### Run Frontend Verification Checks

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/DEVELOPMENT.md

Performs standard local verification checks for the frontend. 'ci-check' runs a stricter verification pass similar to CI.

```bash
just check			# Run the standard local verification pass
```

```bash
just ci-check		# Run the stricter CI-style verification pass
```

--------------------------------

### Conditional Rendering for Book Reading Sessions

Source: https://github.com/grimmory-tools/grimmory/blob/develop/frontend/src/app/features/metadata/component/book-metadata-center/book-reading-sessions/book-reading-sessions.component.html

Handles loading, empty, and populated states for displaying reading sessions. Use this to manage the UI based on the presence of session data.

```HTML
@if (loading() && sessions.length === 0) {

{{ t('loading') }}

} @else if (sessions.length === 0) {

{{ t('emptyState') }}

} @else { {{ t('headerSession') }} {{ t('headerType') }} {{ t('headerDuration') }} {{ t('headerProgress') }} {{ t('headerProgressDelta') }} {{ t('headerLocation') }}{{ formatSessionDate(session.startTime) }} {{ formatTime(session.startTime) }} → {{ formatTime(session.endTime) }}

{{ formatBookType(session.bookType) }} {{ getActualDuration(session) }} @if (session.startProgress !== null && session.startProgress !== undefined && session.endProgress !== null && session.endProgress !== undefined) { {{ session.startProgress }}% → {{ session.endProgress }}% } @else { \- } @if (session.progressDelta !== null && session.progressDelta !== undefined) { {{ (session.progressDelta > 0 ? '+' : '') + session.progressDelta }}% } @else { \- } @if (session.startLocation && session.endLocation) { {{ formatLocation(session) }} } @else { \- } }
```