Configuration Reference

Values used in snippets are the default properties.

Environment Variables

Properties that have an environment variable specified will override the respective property in konifer.conf.

The order of configuration precedence is:

1. Environment variable (for available properties)
2. Property in konifer.conf
3. Default value (if specified)

Datastore

Properties for configuring the datastore.

data-store {
  provider = postgresql
  postgresql {
    database = konifer
    host = localhost
    port = 5432
    user = postgres
    password = ""
  }
}

Property	Description	Allowed Input	Default	Environment variable
data-store.provider	The implementation of your data store	in-memory, postgresql	postgresql	IN_MEMORY*
data-store.postgresql.database	Database to use within the RDBMS	String	konifer
data-store.postgresql.host	Postgresql host	String	localhost
data-store.postgresql.port	Postgresql port	Integer	5432
data-store.postgresql.user	Postgresql user	String	postgres	PG_USER
data-store.postgresql.password	Postgresql password	String	""	PG_PASSWORD
data-store.postgresql.ssl-mode	Postgresql SSL Mode	String	prefer

If IN_MEMORY=true is set as an environment variable, both the data store and object store providers will be set to in-memory.

HTTP

http {
  public-url = "http://localhost"
}

Property	Description	Allowed Input	Default
http.public-url	The URL used to resolve content selector links. This is the root public URL of your website/platform/API.	Any URL beginning with http:// or https://	http://localhost

Object Store

Properties for configuring the datastore.

objectstore {
  provider = filesystem
  s3 { # No defaults - overrides Default Provider Chain if supplied
    access-key = "[no default]"
    endpoint-url = "[no default]"
    region = "[no default]"
    secret-key = "[no default]"
  }
  filesystem {
    mount-path = "[no default]"
  }
}

Property	Description	Allowed Input	Default	Environment variable
objectstore.provider	The implementation of your object store	in-memory, s3, filesystem	filesystem	IN_MEMORY*
objectstore.s3.access-key	The access key of your S3 (or S3-compatible) object store	String	None
objectstore.s3.endpoint-url	The endpoint URL of your S3 (or S3-compatible) object store	String	None
objectstore.s3.region	The region of your object store	String	None
objectstore.s3.secret-key	The secret key of your object store	String	None	S3_SECRET_KEY
objectstore.s3.force-path-style	Communicate with S3 API using path-style or virtual-host style	Boolean	false
objectstore.filesystem.mount-path	The path that your filesystem is mounted to within your container	Valid linux path (ex: /mnt/store)	None

If IN_MEMORY=true is set as an environment variable, both the data store and object store providers will be set to in-memory.

Source

source {
  url {
    allowed-domains = []
    max-bytes = 1048576 # 100MB
  }
  multipart {
    max-bytes = 1048576 # 100MB
  }
}

Property	Description	Allowed Input	Default
source.url.allowed-domains	Domains that Konifer is permitted to access when storing assets from a URL source	Any valid domain	[]
source.url.max-bytes	Maximum size of supplied asset content downloaded from URL. Will reject assets larger than this.	Positive integer representing bytes	1048576
source.multipart.max-bytes	Maximum size of supplied asset content uploaded from Multipart source. Will reject assets larger than this.	Positive integer representing bytes	1048576

Variant Profiles

variant-profiles {
  # Empty by default
  "profile-name" {
  }
}

Property	Description	Allowed Input	Default
variant-profiles	Map of defined variant profiles that canfor eager variants and on-demand variants. Keyed by the profile name	Variant profile object	{}

All image transformation parameters can be used within a variant profile object.

Variant Generation

variant-generation {
  queue-size = 1000
  synchronous-priority = 80
  workers = [2 X CPU cores]
}

Property	Description	Allowed Input	Default
variant-generation.queue-size	Amount of variant generation requests that can be queued up awaiting processing. Requests over this limit suspend the request.	Positive integer	1000
variant-generation.synchronous-priority	Percentage priority to give to synchronous variant generation tasks. The remaining priority is reversed for async tasks.	1-99	80
variant-generation.workers	Amount of concurrent image processor workers	Positive integer	2 x CPU cores

URL Signing

url-signing {
  enabled = false
  algorithm = hmac_sha256
  secret-key = "[no default]"
}

Property	Description	Allowed Input	Default	Environment variable
url-signing.enabled	Enable url-signing for GET requests or not	Boolean	false
url-signing.algorithm	HMAC signing algorithm that signatures use	hmac_sha256, hmac_sha384, hmac_sha512	hmac_sha256
url-signing.secret-key	HMAC secret key used for validating signatures	String	None	URL_SIGNING_SECRET_KEY

Path Configuration Reference

By default, nothing is configured within paths. If nothing is configured, the default configuration below is used.

paths {
  # Match everything greedily after /
  "/**" {
    image {
      lqip = []
    }
    transform {
      preprocessing {
        enabled = false
        image {
          # Preprocessing disabled by default
          # Populate with URL manipulation parameters i.e. w = 100, h = 200, r = 90, etc.
        }
      }
      eager-variants = []
      on-demand-variant {
        mode = enabled
      }
      expire {
        strategy = never
        ttl = [no default]
      }
    }
    object-store {
      bucket = assets
    }
    return-format {
      redirect {
        strategy = none
        template {
          string = localhost
        }
        presigned {
          enabled = false
          ttl = 30m
        }
      }
    }
    cache-control {
      enabled = false
      max-age = "[no default]"
      s-maxage = "[no default]"
      visibility = "[no default]"
      revalidate = "[no default]"
      stale-while-revalidate = "[no default]"
      stale-if-error = "[no default]"
      immutable = false
    }
  }
}

Image

"/**" {
  image {
    lqip = []
  }
}

Property	Description	Allowed Input	Default
image.lqip	LQIP algorithms enabled	blurhash, thumbhash	[]

Transform

Preprocessing

"/**" {
  transform {
    preprocessing {
      enabled = false
      image {
        # Preprocessing disabled by default
      }
    }
  }
}

Property	Description	Allowed Input	Default
transform.preprocessing.enabled	Enable preprocessing	Boolean	false

All image transformation parameters can be used within the image block as well as:

Property	Description	Allowed Input	Default
transform.preprocessing.image.max-height	Maximum height	Integer	None
transform.preprocessing.image.max-width	Maximum width	Integer	None

note

h and w take precedence over max-height and max-width respectively, if both are specified.

Eager Variants

"/**" {
  transform {
    eager-variants = []
  }
}

Property	Description	Allowed Input	Default
transform.eager-variants	List of variant profiles to generate eager variants from	profiles names from variant-profiles array	None

On-demand Variant

"/**" {
  transform {
    on-demand-variant {
      mode = enabled
    }
  }
}

Property	Description	Allowed Input	Default
transform.on-demand-variant.mode	On-demand variant generation mode	enabled, profile_only, disabled	enabled

Expiration

"/**" {
  transform {
    expire {
      strategy = never
      ttl = [no default]
    }
  }
}

Property	Description	Allowed Input	Default
transform.expire.strategy	The variant expiry strategy to use	never, ttl, idle	never
transform.expire.ttl	The time-to-live (in Duration format) used in idle or ttl strategies. Ignored when strategy is never.	Duration e.g. 24h, 7d, 10m	No default

Duration

A duration is represented similarly to how Spring accepts a Duration property value. The time unit is appended to the amount. Units can be:

• s for seconds
• m for minutes
• h for hours
• d for days

note

Due to how expired variants are purged, expiration may be delayed by up to 1 minute after the configured TTL.

Object Store

"/**" {
  object-store {
    bucket = assets
  }
}

Property	Description	Allowed Input	Default
object-store.bucket	Bucket to persist assets and variants in. This can be safely changed without de-referencing existing assets, however, existing assets are not moved to new bucket.	Valid bucket name	assets

Return Format

"/**" {
  return-format {
    redirect {
      strategy = none
      template {
        string = localhost
      }
      presigned {
        ttl = 30m
      }
    }
  }
}

Property	Description	Allowed Input	Default
return-format.redirect.strategy	How to serve redirect URLs	none, presigned, template	none
return-format.redirect.template.string	Template string to use if strategy is template	Valid URL string	localhost
return-format.redirect.presigned.ttl	Time-to-live for presigned redirect URLs if strategy is presigned	Duration-style format. Not less than 7 days (7d)	30m (30 minutes)

Cache Control

"/**" {
  cache-control {
    enabled = false
    max-age = "[no default]"
    s-maxage = "[no default]"
    visibility = "[no default]"
    revalidate = "[no default]"
    stale-while-revalidate = "[no default]"
    stale-if-error = "[no default]"
    immutable = false
  }
}

Property	Description	Allowed Input	Default
enabled	Whether the Cache-Control header should be returned	Boolean	false
max-age	Set the max-age descriptor	Integer > 0
s-maxage	Set the max-age descriptor	Integer > 0
visibility	Set the visbility of the cached asset	public, private
revalidate	Cache control revalidation	must-revalidate, proxy-revalidate, no-cache
stale-while-revalidate	Set the stale-while-revalidate descriptor	Integer > 0
stale-if-error	Set the stale-if-error descriptor	Integer > 0
immutable	Whether to set the immutable descriptor	Boolean	false