Configure Konifer

The quickstart uses IN_MEMORY=true so you can try Konifer without configuring infrastructure. Before using persistent storage, path policies, variant profiles, or delivery settings, create a konifer.conf file.

konifer.conf is a HOCON file that describes how Konifer connects to its dependencies and how it should behave. Keep it outside the container and mount it when the container starts.

Where configuration belongs

Keep the configuration with the deployment definition for each environment. A simple local layout might be:

konifer/
├── konifer.conf       # Non-secret configuration
├── konifer.env        # Secrets; do not commit this file
└── compose.yaml       # Or another deployment definition

Mount konifer.conf at /app/config/konifer.conf. The container reads that path automatically:

docker run --detach \
  --name konifer \
  --publish 8080:8080 \
  --env-file ./konifer.env \
  --mount type=bind,source="$(pwd)/konifer.conf",target=/app/config/konifer.conf,readonly \
  ghcr.io/dmaiken/konifer:0.13.0

Use an absolute path instead of $(pwd) when your deployment system does not run from the configuration directory.

Start with a small configuration

This example describes the essential persistent deployment settings: PostgreSQL for asset information, S3-compatible storage for image content, and a default bucket for every asset path.

konifer.conf

data-store {
  provider = postgresql

  postgresql {
    host = "postgres.internal"
    port = 5432
    database = "konifer"
    ssl-mode = "require"
  }
}

object-store {
  provider = s3

  # Konifer respects the AWS Credential Provider chain, so this may be omitted when that is available
  s3 {
    endpoint-url = "https://s3.example.com"
    region = "us-east-1"
  }
}

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

Replace the hostnames and bucket with values for your environment. Create every configured bucket before starting Konifer.

The default delivery strategy sends clients through Konifer's /content endpoint. Its absolute URL uses the incoming request's scheme, host, and port, so http.public-url is not required for local use. In a deployment where the public origin differs from the incoming request origin, set it explicitly:

http {
  public-url = "https://images.example.com"
}

The paths block is where image behavior becomes application-specific. Start with a default rule, then add more specific paths as your needs grow:

variant-profiles {
  thumbnail {
    w = 256
    h = 256
    fit = fill
    g = attention
  }
}

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

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

More-specific path rules inherit from broader rules. See Path configuration for the full model. For example, in the above configuration, /public/avatars/** inherits the bucket configuration from /**.

Konifer supports singular * and greedy ** wildcards.

Keep secrets out of konifer.conf

Use konifer.conf for non-secret settings: provider choices, hostnames, bucket names, path rules, transformation profiles, and an optional public URL. Supply secrets through your platform's secret mechanism or supported environment variables:

konifer.env

PG_USER=konifer
PG_PASSWORD=replace-with-a-database-password
S3_SECRET_KEY=replace-with-an-object-store-secret
URL_SIGNING_SECRET_KEY=replace-with-a-signing-secret

Only set URL_SIGNING_SECRET_KEY when URL signing is enabled.

warning

Do not commit konifer.env into source control. In a container orchestrator, use its secret-management facility instead.

For settings that support an environment variable, precedence is:

1. Environment variable
2. konifer.conf
3. Built-in default

Continue from here

Use the Configuration reference to find every property and its default.

When you are ready to run PostgreSQL and object storage, continue to Deploying Konifer.