Running multiple image instances

A single Everlock process can host many independent photo libraries at once. Each library is an image instance: its own storage, its own hostnames, its own access grants, and its own gallery. This is the same multi-tenant model Everlock uses for sites and OCI registries — one backend module, many logical instances, selected by Host.

Why multiple instances

A separate instance is the right boundary when two collections should not share storage or access:

• a private family album and a public portfolio from the same box;
• one library per household member, each with its own grants;
• a staging instance you can wipe without touching the real one;
• a LAN-only gallery (.local) alongside a publicly reachable one.

If you only need one library, you do not need any of this — the getting-started guide bootstraps a single default instance from CLI flags.

What each instance owns

flowchart TD
Req["HTTP request"] --> FE["frontend-http (Host header)"]
FE -->|photos.example.net| A["instance: family"]
FE -->|portfolio.example.com| B["instance: work"]
FE -->|kids.local| C["instance: kids"]
A --> AS[("store: family-images")]
A --> AP["grant: http/image/family"]
B --> BS[("store: work-images")]
B --> BP["grant: http/image/work"]
C --> CS[("store: kids-images")]
C --> CP["grant: http/image/kids"]

Each instance has, independently of the others:

The instance name (the TOML table key) is the stable identifier. It keys the Everlock access path, so renaming an instance changes who can reach it — treat it as permanent once grants exist.

The config file is the source of truth

Multi-instance setups live in config/image-http.toml inside the Everlock system store. Once that file exists, it is authoritative and the CLI bootstrap flags (--backend-image-http-vhost, --backend-image-http-store, --backend-image-http-public-url) are no longer consulted for instance layout.

# Enables the backend; the same as passing --backend-image-http.
enabled = true

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

[instances.work]
store = "work-images"
vhosts = ["portfolio.example.com"]
public_url = "https://portfolio.example.com"

[instances.kids]
store = "kids-images"
vhosts = ["kids.local"]

See the engine page for the meaning of every key.

Managing instances from the admin console

You can do most instance management without hand-editing the TOML. From the admin SSH console:

/image list                                    list instances and their vhosts
/image create photos store=family-images vhost=photos.example.net
/image set    photos vhost=photos.local        add a vhost to an instance
/image unset  photos vhost=photos.local        remove a vhost
/image delete photos                           remove an instance

When a change takes effect

Every /image command applies while the process runs, and the answer says so — active immediately:

The two take different routes to the same result. A vhost change is a routing update, because routing is a runtime map. The others are baked into a running instance, so the backend rebuilds that instance in place and swaps it in; the previous settings stay active if the rebuild fails.

A command run while the image backend is not running writes the change to config and asks for a restart, because there is nothing live to apply it to. A .local vhost is announced over mDNS the moment the command returns.

Addressing the instances

Routing only gets a request to the right instance once the client's Host header matches a configured vhost. How clients learn that hostname is the next question, and it splits by environment:

• Public internet — map each public vhost in DNS and let Everlock issue a per-host TLS certificate. See Public hosting: DNS vhosts and ACME.
• Private / home network — use .local vhosts and let Everlock announce them over mDNS so no DNS server is needed at all. See Private networks: mDNS discovery.

A single instance can carry both kinds of vhost at once — a public name for remote access and a .local name for the LAN.

Operator notes

• A usable instance needs at least one vhost; an instance with none is unreachable.
• Large image traffic produces many store commits — size storage accordingly.
• Per-instance grants are independent: a user with owner on family has no access to work unless granted separately.

Read next

• The apimeister-photos engine (ami)
• Public hosting: DNS vhosts and ACME
• Private networks: mDNS discovery
• Image instance and access reference