Lightweight Danbooru-style imageboard engine for the purposes of self-hosting a tagged image gallery.
[kona-web] Implement mass selection and tagging.
[kona-web] Implement infinite scroll.


browse  log 



You can also use your local clone with git send-email.

#Kona: An Imageboard Engine

Kona is a lightweight Danbooru-style imageboard engine for the purposes of self-hosting a tagged image gallery. It lacks many of the features one would expect of such an application (particularly user authentication), so if you have a use case other than being able to search through your pictures when you are not at home, you would be better off looking at an established solution such as Danbooru.

This is a very early release. Perhaps pre-alpha, if there is no earlier stage in the software release life cycle. Use at your own risk.

If you are brave enough to give this a try, however, feedback is appreciated. The command-line interface and web UI are designed around my specific use case, but I would ideally like for this to be usable by anyone.


  • A command-line tool for interacting with the tag database.
  • A web interface for querying and viewing files in the tag database.
    • Works with JavaScript disabled.
    • Infinite scroll when JavaScript is enabled.
    • Interface for tagging multiple images at once when JavaScript is enabled.



There are two ways of interacting with бирка-тян: through the kona-cli command-line tool (i), and through the web interface (ii).

The inclusion of (i) is in consideration for this being, essentially, a personal image gallery. One likely has a loosely-organized collection of images already; the command-line tool enables her to import images en masse with the full capabilities of the Unix shell at her fingertips. A brief summary of the command-line interface follows.

Images are introduced to the database with the add command, which takes zero or more tags following the path of an image. The path is automatically canonicalized, so relative names are perfectly acceptable.

$ kona-cli add Cat.jpeg animal cat cute

Ah, drat. We should have tagged that image with "photograph", too.

$ kona-cli add_tags Cat.jpeg photograph

On second thought, that wasn't a particularly cute picture.

$ kona-cli remove_tags Cat.jpeg cute

Now, let's see all of the photographs in the tag database tagged with "photograph".

$ kona-cli query photograph

The query command outputs a line-separated list of paths to any images satisfying the query string. The semantics are similar to that of Danbooru, except that the logical disjunction operator ('~') is unsupported. As a convenience, the 'query' command can be invoked without a query string, to list all paths indexed by the database.

$ kona-cli query

The tag database is stored in a file, and the path of that file is dependent on how the program is invoked. If, when parsing the command-line arguments, kona-cli sees a -o or --output argument, the path following that argument will be used. Alternatively, the TB_PATH environment variable can be specified, but -o takes a higher precedence. If neither are specified, "kona.db" in the current directory is used.

A few other things that can be done from the command-line:

Removing an image can be done with 'remove'.

$ kona-cli remove Cat.jpeg

Getting the tags in the database:

$ kona-cli tags

#Web-Interface (API)

The web interface for бирка-тян exposes a RESTful API for remotely interacting with the tag database. At the time of writing, this API is not stabilized. Expect to rewrite any code depending on this API in the near future, in part because these will all be put behind a /v1/ specifier.

Suppose we denote the following shape of JSON object as a ImageResult.

  "id": number,
  "filename": string,
  "thumb_filename": string,
  "orig_filename": string,
  "tags": [string, ...],

The images in the tag database can be enumerated with the 'posts' endpoint, which takes two parameters: query, a query string, and last, which is the last ImageResult identifier which was seen. This endpoint will return, at most, 50 entries, which is why the last parameter is necessary.

GET /api/posts?last=number,query=string

[zero or more ImageResult]

Information about a specific image in the database can be obtained with the following endpoint, where id is the identifier (number) of the image in the database:

GET /api/posts/[id]


To add tags to an image, POST a comma-separated list of new tags to the same endpoint.

To upload an image to the database, post a multipart/form-data encoded message to the following endpoint with the following fields: tags, a comma-separated list of tags for the files, and image, the file to be uploaded.

POST /api/posts


There are a few things I'd like to push off 'till later, since this is working for me right now.

  • [kona-cli] Improve the kona-cli add interface, allowing multiple files to be indexed and tagged in the same invocation.
  • [kona-web] Redesign parts of the API, tend to unorthogonalities.
  • [kona-web] Properly document the API.
  • [kona-web] Visual facelift.