DOCSEARCHbyAlgolia
Submit Docs

Konifer Documentation

website·Indexed 30 days ago

https://konifer.io

Konifer is an image infrastructure platform for managing assets and generating transformed variants. It features a dual-store architecture using an object store and database, a Rule Evaluation API for comparing images against natural-language rule definitions, and a robust suite of image transformation options powered by libvips.

Tokens
22.9K
Snippets
128
Records
179
Agent score
49%

What's inside Konifer

  1. Overview of Konifer image infrastructure

    Konifer is an API-first image infrastructure service that allows applications to store, transform, and deliver images using their own domain-model paths rather than opaque asset identifiers. It manages original images, generates and caches transformed variants, and handles delivery as content, links, redirects, or downloads.

  2. Overview of Konifer Storage Architecture

    Konifer uses a dual-store architecture to separate physical asset storage from relational data:

    1. Object Store: Stores physical variant binaries. Supported providers include AWS S3, S3-compatible stores, filesystem, and in-memory.
    2. Metadata Store: Stores relational data, path hierarchies, tags, and labels. Supported engines are PostgreSQL and in-memory.

  3. Enable Low-Quality Image Previews (LQIP) in Konifer

    Low-quality image previews (LQIPs) are small, blurry versions of images displayed while the full-resolution image downloads. Konifer supports two implementations: BlurHash and ThumbHash. LQIPs are generated alongside image variants (either eagerly or on-demand) and are only regenerated when necessary (e.g., they are not regenerated for blur transformations to save compute).

    LQIPs are disabled by default and must be enabled within the Path Configuration.

  4. Konifer storage and delivery architecture

    Konifer separates the storage of image files from the storage of asset metadata:

    • Image Files: Stored on a local filesystem or S3-compatible object storage.
    • Asset Records: Metadata, paths, and variant states are stored in PostgreSQL.
    • Delivery: Images can be served via direct image links, HTTP redirects to object storage, or returned as content from the API, with optional CDN integration.

  5. Understand Konifer variant caching and normalization

    Konifer caches variants (generated either eagerly or on-demand) in the configured object store. To optimize storage and avoid redundant processing, Konifer normalizes variant requests. This means that different request parameters that result in the same visual output are mapped to the same cached variant.

    For example, a request for a horizontal flip combined with a 180-degree rotation produces the same image as a vertical flip. Konifer recognizes this equivalence and serves the same cached asset for both requests.

    # These two requests resolve to the same cached variant
GET /assets/users/123/profile-picture?f=h&r=180
GET /assets/users/123/profile-picture?f=v

  6. Generate Cloudflare R2 API credentials for Konifer

    Konifer requires S3-compatible credentials to access R2. These must be generated in the Cloudflare dashboard:

    1. Navigate to Storage & databases > R2 > Overview.
    2. Under API Tokens, select Manage.
    3. Create an API token with Object Read & Write permissions, scoped to the specific buckets needed.
    4. Save the Access Key ID and Secret Access Key (the secret is only shown once).
    5. Note the S3 API URL, which follows the format: https://<ACCOUNT_ID>.r2.cloudflarestorage.com.

  7. Understand how Konifer rule evaluation works

    Rule evaluation compares an image against one or more natural-language rule definitions using the SigLIP2 zero-shot image classification model. For each definition, Konifer embeds the image and compares it with every prompt in that definition. The highest prompt score is used as the definition's overall score. If this overall score is greater than or equal to the definition's threshold, the result is marked as matched: true.

    Key characteristics:

    • Scores are model scores, not confidence percentages or probabilities.
    • Evaluating an image via the API does not store the image or create an asset.
    • Definitions provided in the API request are evaluated directly and do not need to exist in the global rule-definitions configuration.

  8. Create and organize assets in Konifer

    Assets are the fundamental resources in Konifer, consisting of information (stored in Postgres) and immutable content (stored in an object store like S3, filesystem, or in-memory). Assets are created by performing a POST request to a user-defined path, allowing you to define your own domain structure (e.g., organizing by user ID or blog post ID). If multiple assets are created at the same path, the most recently created asset is returned by default when fetching.
    # Example: Organizing assets by user
POST /assets/users/123/profile-picture

# Example: Organizing assets by blog post
POST /assets/blog/123/post/5

  9. Understand Konifer's dual-store architecture

    Konifer uses a dual-store architecture to separate physical asset content from its descriptive data:

    1. Object Store: A key-value blob store used to persist physical variant content (binaries).
    2. Metadata Store: A relational database used to persist path hierarchies, tags, labels, and other relational data.

  10. Understand Konifer configuration precedence

    Konifer applies configuration settings in the following order of precedence (highest priority first):

    1. Environment variables (where available)
    2. Properties defined in the konifer.conf file
    3. Default values

  11. Understand the Original Variant in Konifer

    The Original Variant is the physical representation of the asset content supplied during the Store Assets request. It serves as the base for all other variants; every other variant for an asset is transformed from the Original Variant. If no pre-processing is configured, the Original Variant is an exact representation of the supplied content. If pre-processing (such as global clamp-width or format conversion) is configured, it transforms the supplied content into the Original Variant.

  12. Determine if Konifer is a fit for your image management

    Konifer is designed for applications where images are tied to identifiable domain resources (e.g., users, products, tenants) and for teams that want full control over their storage, transformation, and delivery infrastructure. It is a strong fit if you need:

    • Resource-based paths: The ability to derive image paths from existing application data (e.g., /assets/tenants/{tenantId}/products/{sku}/hero) without storing separate image IDs for every request.
    • Lifecycle management: Integrated original-image storage, replaceable images, version history at stable paths, and on-demand/eagerly generated variants.
    • Path-based policies: The ability to apply different storage, validation, preprocessing, and caching behaviors based on the image path (e.g., different rules for /public/avatars/** vs /claims/**/evidence).
    • Infrastructure control: A self-hosted model using PostgreSQL and S3-compatible or filesystem storage, integrating directly with your own network and CDN.
    // Example of deriving a path from application identifiers
val path = "/assets/tenants/$tenantId/products/$sku/hero"