- Python 71.7%
- HTML 17.6%
- Makefile 10.7%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| plugins/tagger | ||
| scripts | ||
| ui | ||
| vski/gallery | ||
| .env.example | ||
| .gitignore | ||
| docker-compose.yml | ||
| Dockerfile.minio | ||
| Dockerfile.vski | ||
| Makefile | ||
| README.md | ||
example_gallery_tagger
An image gallery that tags itself. Upload a photo and a collection trigger wakes a Python plugin that captions and tags the image with a local Ollama vision model, embeds the caption, and writes everything back, so the gallery becomes searchable by meaning, not just by tag. All files live in S3-compatible object storage (MinIO), which also makes this project the end-to-end exercise of vski's S3 file storage mode.
upload (multipart)
|
v
+------------------------------+
| vski :3102 | S3 bucket "gallery"
| photos collection |----> photos/{recordId}/{file}
| trigger on update | (MinIO :9000, console :9001)
+------------------------------+
| plugin://tagger/on_photo
v
+------------------------------+ +---------------------+
| tagger plugin (in container) |---->| Ollama on the host |
| 1. download image via /files | | gemma4:12b caption |
| 2. caption + tags (vision) | | nomic-embed-text |
| 3. embed caption | +---------------------+
| 4. write caption/tags back |
+------------------------------+
| |
v v
photos.caption/tags photos embeddings (vector search)
Layout
docker-compose.yml MinIO + vski (S3 mode, plugin runtime in-container)
Dockerfile.vski vski image + Python + vski SDK (plugin runtime)
Dockerfile.minio local MinIO image, only for networks that cannot
pull minio/minio from Docker Hub
vski/gallery/ IaC: photos collection (+ trigger), tagger instance
plugins/tagger/ the tagger plugin (manifest + package)
scripts/ setup (bucket, admin, keys), seed, retag, status,
search, lsbucket
ui/ single-file gallery UI (needs config.js from setup)
Requirements
- Docker with the compose plugin
- Ollama on the host with a vision model and a text
embedding model. Defaults expect
gemma4:12bandnomic-embed-text(ollama pulleach). Any vision model works; changecaption_modelinvski/gallery/plugins.yaml. - Port 3102 (vski), 9000/9001 (MinIO), 8090 (UI) free on 127.0.0.1
Quick start
cp .env.example .env
make up # MinIO + vski in S3 mode
make setup # S3 bucket, first admin, admin + viewer API keys
make iac-apply # gallery db, photos collection, tagger plugin instance
make seed # download 12 photos and upload them
make status # watch captions arrive (about a minute per photo)
make ui # gallery at http://127.0.0.1:8090
Browse the bucket itself at http://127.0.0.1:9001 (console credentials are
the MINIO_ROOT_USER / MINIO_ROOT_PASSWORD from .env).
Semantic search from the terminal:
make search q="misty mountain ruins"
The query is embedded with the same model the tagger used and matched against the stored caption vectors, so it finds photos whose captions are close in meaning even when no tag matches.
How the pieces work
Storage (the S3 part). With S3_BUCKET set, vski stores every uploaded
file as an object keyed {collection}/{recordId}/{filename}, mirroring the
local-disk layout, and the /files/{collection}/{recordId}/{filename}
download route streams objects straight from the bucket. The replica file
journal is off in S3 mode: the bucket is the shared storage. Deleting a
record deletes its objects.
Uploads. A photo upload is one multipart POST: form fields become the
record, each file part lands in storage under its field name, and the
filename is stored in the image field. File parts are merged into the
record before validation, so image can be (and is) required.
The trigger loop, without a loop. The multipart save publishes an update
event, the collection trigger hands the record to plugin://tagger/on_photo,
and the plugin writes its results back, which fires the same trigger again.
The taggedFile field records which file the current tags describe: when it
equals image, the plugin skips (that is also why re-uploading a new image
to an existing record re-triggers tagging). Replace the image or run
make retag to force a re-run.
Slow work, fast ack. Captioning a photo with a local vision model takes
tens of seconds, longer than a trigger invocation may run, so on_photo
acknowledges immediately and processes in a background task, one photo at a
time (a semaphore keeps Ollama un-thrashed). Failures are written to the
record's state/error fields, never thrown at the trigger.
Access. The gallery UI reads records with a viewer-role API key (read
rules on photos allow viewer; the tagger plugin's service role plugin
can update; writes and uploads use an admin key). Note that the /files/...
download route is public by design: anyone with the URL can fetch a file.
Restricted networks
Docker Hub org images (minio/minio) are unreachable on some networks. This
repo can build MinIO from source instead (needs Go >= 1.26):
make minio-binary # compiles bin/minio
make minio-image # builds image minio-local:dev
# then set in .env: MINIO_IMAGE=minio-local:dev
The same override exists for the vski image itself (VSKI_IMAGE in .env,
defaulting to a build with S3 support; the demo image adds Python for the
plugin runtime).
Making it yours
- Point
PHOTOSinscripts/seed.pyat your own images, or upload from the dashboard (records view supports file fields) or any SDK client. - Swap the vision or embedding model in
vski/gallery/plugins.yamlandmake retag(with a new embed model, tag fresh records or delete the old vectors first; a collection pins its embedding model and dimensions on first write). - Change the prompt in
plugins/tagger/tagger/main.pyto extract different metadata (colors, subjects, license plates, whatever your gallery needs). - The plugin only demonstrates local Ollama; any OpenAI-compatible vision endpoint works with the same code shape.
Teardown
make down # stop containers
make clean # also wipe volumes, venv, cached assets