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.

How instances share the machine

Instances keep their data apart, but they run on the same CPU, memory and disk, and they compete for them. Each instance runs one background job at a time and rests for its cooldown after each one, independently of the others:

• Duplicate detection, federation sync and video posters can run at the same time in different instances.
• AI captions from all instances share one queue and take turns, so two busy instances each caption at about half the speed of one.
• A cooldown only pauses its own instance. While another instance still has photos to caption, the AI keeps working through its cooldown.

An instance with a small backlog soon finishes and stops competing. Admin AI prompts are not part of this: they run separately and do not wait for captions.

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