Image instance and access reference

This page covers image instances, routing, and access control for Everlock's image service. The underlying media engine is apimeister-photos; running several instances at once is covered in Running multiple image instances.

Service model

served over frontend-http
host-dispatched by vhost, similar to sites and OCI
authenticated through Everlock users
authorized through Everlock grants on http/image/<instance>

What it does

provides an HTTP-facing image and media backend
supports multiple logical image instances from one Everlock process
integrates with jobs for derived work
is meant to stay transport-agnostic behind the HTTP frontend
can generate image captions through the shared AI runtime without loading a second model

Managing instances

Instances are managed through the admin CLI:

/image list
/image create <name> [store=<name>] vhost=<host>
/image set    <name> vhost=<host>
/image unset  <name> vhost=<host>
/image delete <name>

Adding or removing vhosts takes effect immediately without a restart. Creating or deleting an instance requires a restart.

Instance layout

Each instance has:

one Everlock store
one or more vhost names
one Everlock access path http/image/<instance>

The public URL advertised by the instance is derived automatically from the primary vhost (https://<first-vhost>). To use a different scheme or port, set public_url explicitly in config/image-http.toml:

# Top-level switch; equivalent to --backend-image-http.
enabled = true

[instances.default]
store = "everlock-image"
vhosts = ["images.example.com"]

[instances.family]
store = "family-images"
vhosts = ["photos.example.net", "photos.local"]
# public_url = "https://photos.example.net"
instance_name = "The Family Album"
enhance_languages = ["en", "de"]

Per-instance config keys

Key	Required	Purpose
`store`	yes	Everlock store backing this instance; never share one between instances
`vhosts`	yes (≥1)	Hostnames that route to the instance
`public_url`	no	Absolute base URL advertised to clients; derived from the first vhost when unset
`instance_name`	no	Cosmetic display name shown in the gallery; does not affect routing or the access path
`enhance_languages`	no	BCP 47 language tags for AI-generated captions (e.g. `["en", "de"]`); empty means English only

See the engine page for the full meaning of each key.

The CLI flags --backend-image-http-vhost and --backend-image-http-store also provide a bootstrap path that creates a single instance named default. The --backend-image-http-public-url flag is still accepted but no longer necessary since the URL is derived from the vhost.

How vhosts are reached

The kind of hostname decides how a client reaches the instance:

public DNS names become ACME-managed HTTPS;
.local names are announced over mDNS and served plain HTTP;
localhost and raw IPs stay plain HTTP for local use.

localhost, *.local, and raw IPs are never ACME-managed. One instance can mix all three; public_url derives from whichever vhost is listed first.

Two things to remember when bootstrapping from the CLI:

--backend-image-http enables the backend
runtime flags go after the serve subcommand

./everlock serve \
  --backend-image-http \
  --backend-image-http-vhost img.local

Access control

The image backend uses one Everlock access path per configured image instance:

http/image/<instance>

The default instance name is default, so the default path is:

http/image/default

Role mapping is HTTP-method based:

Reader for GET / HEAD / OPTIONS
Writer for POST / PUT / PATCH
Owner for DELETE

Examples:

/users grant alice http/image/default reader
/users grant alice http/image/default writer
/users grant alice http/image/default owner

Password login for the embedded image app is backed by Everlock users. A user must have at least Reader on the image instance to log in at all.

Public anon access is not available for the image backend.