Enabling Search

Search is off by default. When you enable it, members can search every room that they can read, and each room separately. The bundled provider keeps a full-text index in a local directory and builds it from your message history.

Enable Search

For a new installation, generate a configuration with search enabled:

chatto init --with-search
chatto run

The flag enables message search and the bundled provider in chatto.toml. The provider stores its index in ./data/search. You can combine this flag with --with-livekit to configure calls too.

For an existing installation, use these settings:

TOML

[search]
enabled = true

[search_provider]
enabled = true
directory = "./data/search"

Environment

CHATTO_SEARCH_ENABLED=true
CHATTO_SEARCH_PROVIDER_ENABLED=true
CHATTO_SEARCH_PROVIDER_DIRECTORY=./data/search

search.enabled shows Search to members. search_provider.enabled starts the bundled provider inside chatto run.

1. Add the configuration and make sure that Chatto can write to the directory.
2. Restart Chatto.
3. Search shows Indexing until the provider has read your message history. Large servers take longer. The provider logs its progress.

Caution

The index contains text from decrypted messages. Protect it like message data. Use a dedicated directory that does not contain the NATS data directory. Do not include it in backups, and do not share it between two provider processes.

Choose languages

Language analyzers match word forms, such as “run” and “running”. By default, the provider uses all of them. Each analyzer makes the index larger, so select only the languages that your community uses:

[search_provider]
languages = ["en", "de", "fr", "cjk"]

Available codes: ar, cjk (Chinese, Japanese, and Korean), ckb, da, de, en, es, fa, fi, fr, hi, hr, hu, it, nl, no, pl, pt, ro, ru, sv, tr. Use languages = [] (or none in the environment variable) for exact matching only.

A change to the list rebuilds the index automatically at the next start.

Keep the index in memory

To avoid disk use, put the directory on a RAM-backed volume. For Docker Compose:

services:
  chatto:
    tmpfs:
      - /var/lib/chatto/search:size=2g,mode=0700

In Kubernetes, use an emptyDir with medium: Memory. Each restart discards the index, and Search is unavailable while the provider rebuilds it. The index counts toward the memory limit of the process.

Run the provider separately

To move indexing work to a different process or host, disable the bundled provider in the server configuration:

[search]
enabled = true

[search_provider]
enabled = false

Then start the provider with a configuration that can reach the same NATS server:

chatto search-provider --config chatto.toml

The provider uses the other [search_provider] settings. If Chatto uses embedded NATS, expose its client port only to the trusted network.

Use a different provider

You can replace the bundled provider with your own. A provider is a NATS service that implements the chatto.search.v1 protobuf messages on the svc.chatto_ext.search.v1 subjects. Chatto checks permissions again before it returns a result, so a provider cannot give access to a message. A provider sees search terms and message text, so run it as a trusted server component.

Rebuild the search index

The provider rebuilds the index automatically after an upgrade or a language change. It stops with an error when the index is unreadable or the directory contains unknown files. To rebuild the index manually:

1. Stop the process that runs the provider: chatto run for the bundled provider, or chatto search-provider. Prevent automatic restarts.

2. Move the index directory aside:

   mv ./data/search ./data/search.before-rebuild

   Use your search_provider.directory path. Do not remove the parent directory or the NATS data directory.

3. Start the process again. Search shows Indexing until the rebuild is complete.

4. Make sure that Search finds an expected message. Then delete the old directory.

A rebuild does not change messages or accounts.

Troubleshooting

Symptom	Solution
Search is not in the sidebar	Set search.enabled = true and restart Chatto.
Search is unavailable	Make sure that a provider runs and connects to the same NATS server.
Search shows Indexing	Wait for the provider to finish. See its logs for progress.
Word forms do not match	Add the language to search_provider.languages.
Startup rejects the index directory	Use a dedicated directory that does not contain the NATS data directory.
Startup requires index recovery	Rebuild the search index.

See Environment Variables for all settings.