Skip to main content

Getting Started with Konifer

Upload a profile picture, create a WebP thumbnail, and replace the original without changing its URL. You can follow along in about 10 minutes with Docker and curl, or browse the images and example responses below.

1. Start Konifer​

Start a development container on port 8080:

docker run --detach \
--rm \
--name konifer-quickstart \
--publish 8080:8080 \
--env IN_MEMORY=true \
ghcr.io/dmaiken/konifer:1.0.0-rc.2

This evaluation mode uses in-memory storage. You lose the uploaded images and their information when you stop the container.

Verify that Konifer is ready before continuing:

curl --fail \
--retry 10 \
--retry-connrefused \
--retry-delay 1 \
'http://localhost:8080/health/ready'

Open Swagger UI to explore the running server's asset API. The generated OpenAPI specification is available at http://localhost:8080/api/docs/openapi.json. See the OpenAPI reference.

note

Use Docker to run Konifer with its required libvips configuration. We do not provide standalone JARs or binary releases.

2. Store your first image​

Download Mr. Dog and save it as mr-dog-1.jpg. Run the upload command from the folder where you saved the image. You will store it at the /users/123/profile-picture path.

Mr. Dog, a small cute dog

Mr. Dog · Original JPG · 1200×798 pixels. Download Mr. Dog (JPG)

curl --fail-with-body \
--request POST \
--url 'http://localhost:8080/assets/users/123/profile-picture' \
--form 'metadata={"alt":"profile picture"}' \
--form 'asset=@mr-dog-1.jpg'

The response includes "entryId": 0, which identifies this first upload. Keep it to retrieve this picture after you upload a replacement. Your entry ID may differ if you have uploaded to this path before.

Full upload response
{
"class": "image",
"alt": "profile picture",
"entryId": 0,
"labels": {},
"tags": [],
"source": "upload",
"variants": [
{
"isOriginalVariant": true,
"storeBucket": "assets",
"storeKey": "d2128c60-e2e2-4056-ae6a-3d6799b41b83.jpeg",
"attributes": {
"height": 798,
"width": 1200,
"format": "jpg",
"colorSpace": "srgb",
"pageCount": 1
},
"lqip": {}
}
],
"createdAt": "2026-10-15T01:46:42.879461495Z",
"modifiedAt": "2026-10-15T01:46:42.906062144Z"
}

3. View your asset's content​

Open this URL in your browser to view Mr. Dog. The content selector returns the image itself:

http://localhost:8080/assets/users/123/profile-picture/-/content

4. Request a WebP thumbnail​

Open this URL in your browser to create a 256×256 WebP thumbnail. Use fit=fill to fill the square without stretching the image, and gravity=attention to choose which area to keep when cropping:

http://localhost:8080/assets/users/123/profile-picture/-/content?format=webp&width=256&height=256&fit=fill&gravity=attention
Original landscape photo of Mr. Dog
Original JPG · 1200×798 pixels
Square thumbnail of Mr. Dog
WebP thumbnail · 256×256 pixels

You now have the original image and a thumbnail under the same asset path.

note

Konifer respects the Accept header. A format query parameter, when present, takes precedence over the header.

5. View your asset's information​

Open the info URL in your browser to inspect the stored image and its variants:

http://localhost:8080/assets/users/123/profile-picture/-/info

The response includes the original JPG and the WebP thumbnail you requested. This excerpt shows their dimensions and formats; it omits the other response fields:

{
"entryId": 0,
"variants": [
{
"isOriginalVariant": true,
"attributes": { "height": 798, "width": 1200, "format": "jpg" }
},
{
"isOriginalVariant": false,
"attributes": { "height": 256, "width": 256, "format": "webp" }
}
]
}
Full asset information response
{
"class": "image",
"alt": "profile picture",
"entryId": 0,
"labels": {},
"tags": [],
"source": "upload",
"variants": [
{
"isOriginalVariant": true,
"storeBucket": "assets",
"storeKey": "d2128c60-e2e2-4056-ae6a-3d6799b41b83.jpeg",
"attributes": {
"height": 798,
"width": 1200,
"format": "jpg",
"colorSpace": "srgb",
"pageCount": 1
},
"lqip": {}
},
{
"isOriginalVariant": false,
"storeBucket": "assets",
"storeKey": "f68b413f-a5db-4e9a-b38c-613909bd9bc0.webp",
"attributes": {
"height": 256,
"width": 256,
"format": "webp",
"colorSpace": "srgb",
"pageCount": 1,
"loop": 0
},
"transformation": {
"width": 256,
"height": 256,
"fit": "fill",
"gravity": "attention",
"format": "webp",
"rotate": "0",
"flip": "",
"filter": "",
"blur": 0,
"quality": 80,
"padding": {
"amount": 0,
"color": []
},
"metadata": {
"strip": []
},
"colorSpace": "srgb"
},
"lqip": {}
}
],
"createdAt": "2026-10-15T01:46:42.879461495Z",
"modifiedAt": "2026-10-15T01:46:42.906062144Z"
}

6. Upload an updated profile picture​

Replace Mr. Dog's profile picture with a new one. Download the image as mr-dog-2.jpg into the same folder, then upload it to the same path. Konifer creates a new entry without changing the URL your application uses.

Mr. Dog, a cute little dog

Mr. Dog · Replacement JPG · 1200x798 pixels. Download Mr. Dog (JPG)

curl --fail-with-body \
--request POST \
--url 'http://localhost:8080/assets/users/123/profile-picture' \
--form 'metadata={"alt":"profile picture"}' \
--form 'asset=@mr-dog-2.jpg'

The response now includes "entryId": 1. You have two entries at the same path, each with its own entry ID.

Full replacement upload response
{
"class": "image",
"alt": "profile picture",
"entryId": 1,
"labels": {},
"tags": [],
"source": "upload",
"variants": [
{
"isOriginalVariant": true,
"storeBucket": "assets",
"storeKey": "d87ce003-aa51-4e00-b507-30465751e971.jpeg",
"attributes": {
"height": 798,
"width": 1200,
"format": "jpg",
"colorSpace": "srgb",
"pageCount": 1
},
"lqip": {}
}
],
"createdAt": "2026-10-15T01:53:32.95613658Z",
"modifiedAt": "2026-10-15T01:53:32.958626453Z"
}

7. Fetch the new and old profile pictures​

Open the same content URL again to view Mr. Dog's latest profile picture:

http://localhost:8080/assets/users/123/profile-picture/-/content

To view Mr. Dog's old profile picture, add the first upload's entry ID to the URL:

http://localhost:8080/assets/users/123/profile-picture/-/entry/0/content

In a fresh quickstart container, the first entry has an entryId of 0. Use the value returned by your first upload if it differs.

Mr. Dog, the current profile picture
Current picture · Mr. Dog · Entry 1
Mr. Dog, the previous profile picture
Previous picture · Mr. Dog · Entry 0

8. View information for every profile picture​

Open the entries URL in your browser to see both uploads, newest first. By default, Konifer returns up to 20 entries; use the limit query parameter to change that number.

http://localhost:8080/assets/users/123/profile-picture/-/entries

This excerpt shows the two entry IDs. Expand the full response to inspect each entry's variants:

{
"entries": [
{ "entryId": 1 },
{ "entryId": 0 }
]
}
Full entries response
{
"entries": [
{
"class": "image",
"alt": "profile picture",
"entryId": 1,
"labels": {},
"tags": [],
"source": "upload",
"variants": [
{
"isOriginalVariant": true,
"storeBucket": "assets",
"storeKey": "d87ce003-aa51-4e00-b507-30465751e971.jpeg",
"attributes": {
"height": 798,
"width": 1200,
"format": "jpg",
"colorSpace": "srgb",
"pageCount": 1
},
"lqip": {}
}
],
"createdAt": "2026-10-15T01:53:32.95613658Z",
"modifiedAt": "2026-10-15T01:53:32.958626453Z"
},
{
"class": "image",
"alt": "profile picture",
"entryId": 0,
"labels": {},
"tags": [],
"source": "upload",
"variants": [
{
"isOriginalVariant": true,
"storeBucket": "assets",
"storeKey": "d2128c60-e2e2-4056-ae6a-3d6799b41b83.jpeg",
"attributes": {
"height": 798,
"width": 1200,
"format": "jpg",
"colorSpace": "srgb",
"pageCount": 1
},
"lqip": {}
},
{
"isOriginalVariant": false,
"storeBucket": "assets",
"storeKey": "f68b413f-a5db-4e9a-b38c-613909bd9bc0.webp",
"attributes": {
"height": 256,
"width": 256,
"format": "webp",
"colorSpace": "srgb",
"pageCount": 1,
"loop": 0
},
"transformation": {
"width": 256,
"height": 256,
"fit": "fill",
"gravity": "attention",
"format": "webp",
"rotate": "0",
"flip": "",
"filter": "",
"blur": 0,
"quality": 80,
"padding": {
"amount": 0,
"color": []
},
"metadata": {
"strip": []
},
"colorSpace": "srgb"
},
"lqip": {}
}
],
"createdAt": "2026-10-15T01:46:42.879461495Z",
"modifiedAt": "2026-10-15T01:46:42.906062144Z"
}
]
}

Optional: fetch raw pixels​

For image-processing code, request a 224×224 RGB buffer in planar layout:

curl --fail-with-body \
--dump-header profile-picture.headers \
--output profile-picture.bin \
--url 'http://localhost:8080/assets/users/123/profile-picture/-/content?format=pixels&width=224&height=224&fit=fill&color-space=srgb&pixel-channels=RGB&pixel-layout=planar'

Konifer returns 150,528 unsigned 8-bit samples as application/octet-stream. This buffer contains the red plane, then the green plane, then the blue plane. It has no image header. The saved profile-picture.headers contains the dimensions, channel order, layout, and data type in K-Attr-* HTTP headers from the same response.

See Raw Pixels for channel order, grayscale, and preprocessing, and the Fetch Assets reference for client examples.

9. Stop Konifer​

docker stop konifer-quickstart

Because the container was started with --rm, Docker removes it after it stops.

Next steps​

To use Konifer from your application, see Konifer Client.

The quickstart uses temporary in-memory storage. To configure persistent storage, path policies, variant profiles, and delivery behavior, continue to Configure Konifer.

For a production-ready PostgreSQL and S3-compatible deployment, see Deploying Konifer.

To feed raw pixels to a Python inference worker through named variant profiles, follow Prepare Pixels for Inference.