Getting started with the web interface

tessera-web is a local web application that provides a visual file browser, tag editor, search bar, and media previews on top of the same database that the CLI uses.

Starting the server

# Serve the collection in the current directory
tessera-web

# Serve a specific path
tessera-web ~/Photos

# Custom port and bind address
tessera-web --port 8080 ~/Photos

# Include parent databases in queries
tessera-web ~/Photos   # parents are included by default
tessera-web --no-parents ~/Photos

Open http://localhost:4141 in your browser.

Authentication

When binding to localhost (the default), no password is required.

When binding to a non-loopback address (e.g. --bind 0.0.0.0), a random password is automatically generated and printed to stderr. You must supply it on the login page.

To set a specific password:

tessera-web --password mysecretpassword ~/Photos
# or via environment variable:
TESSERA_PASSWORD=mysecretpassword tessera-web ~/Photos
# or read from a file:
tessera-web --password-file /run/secrets/tessera ~/Photos

To generate a random password explicitly:

tessera-web -P ~/Photos   # prints password to stderr

To disable authentication entirely (e.g. behind a reverse proxy that handles auth):

tessera-web --no-auth --bind 0.0.0.0 ~/Photos

Logging

Two independent settings decide what happens to a log record: how much is logged, and where it goes. The startup banner prints the resolved answer to both, so you never have to guess:

Logs: /home/you/Photos/.tessera/logs/tessera.log (info)

--log-level sets the verbosity to off, error, warn, info, debug, or trace; the default is info. TESSERA_LOG sets the same thing for environments where a flag is awkward, and the flag wins when both are given.

Either accepts per-target overrides, so one noisy subsystem can be quietened without dimming the rest:

tessera-web --log-level info,tessera::embedding=error ~/Photos

A target matches on its module-path prefix, longest match first, so tessera::embedding=error also covers tessera::embedding::batch.

Where

The server writes its application log to <primary-root>/.tessera/logs/tessera.log. In a multi-database session this is the single process-wide log; entries concerning another database include that database's root path. The log rotates at 10 MiB and keeps one previous file as tessera.log.1. Use --log-file <path> to write elsewhere, or --log-file none to write no file at all — useful in a container, where the root may be a read-only mount and the collector wants the stream instead.

--log-stderr decides whether records are also streamed to the terminal:

Value	Behaviour
`auto` (default)	Stream only when stderr is not a terminal — a container, a systemd unit, a pipe. An interactive session stays quiet.
`always`	Stream regardless, for watching a run as it happens.
`never`	Never stream; the log file is the only sink.

Records never go to stdout: that stream carries program output, and a stray log line there would corrupt a --json pipeline.

A container therefore usually wants:

tessera-web --log-file none --log-level info ~/Photos   # stderr only, collected by the runtime

and someone debugging locally wants:

tessera-web --log-stderr always --log-level debug ~/Photos

Panics and graceful shutdown signals (SIGINT, SIGTERM, SIGHUP, and SIGQUIT) are recorded with their reason. SIGKILL cannot be caught by any application. Tessera therefore keeps a run marker and reports an unclean prior shutdown on the next start. For the exact cause of a SIGKILL—for example an out-of-memory kill—consult the operating-system or service-manager logs.

See Authentication for more.

Multiple roots

Pass multiple paths to serve several collections at once:

tessera-web ~/Photos ~/Music ~/Documents

The browser shows a root selector at the top of the sidebar.