Configuration¶

Each setting can be given as a command-line flag, an environment variable or a key in dictshelf.toml. The variable and the key have the same name.

Priority¶

Highest first: command-line flag, environment variable, dictshelf.toml, built-in default. The setup page shows which values a flag or variable overrides.

Config file¶

DictShelf reads the first of:

1. --config or CONFIG_PATH
2. dictshelf.toml next to the executable (portable mode)
3. ~/.dmshlabs/dictshelf/dictshelf.toml on macOS and Linux; ~/.dmshlabs/dictshelf/dictshelf.toml on Windows
4. /etc/dictshelf/dictshelf.toml

The first dictshelf serve creates the platform config file with every setting commented out. Each start prints the file in effect. An unknown key is reported at startup and on the setup page.

Portable mode¶

A dictshelf.toml next to the executable takes precedence over ~/.dmshlabs/dictshelf/dictshelf.toml and receives the settings saved from the setup page. DictShelf never creates it.

Files¶

Log when there is no console: macOS ~/Library/Logs/DMSH Labs/DictShelf/dictshelf.log, Linux ~/.dmshlabs/dictshelf/dictshelf.log, Windows %USERPROFILE%\.dmshlabs\dictshelf\db.logs\dictshelf.log, Android logcat.

DictShelf does not modify dictionary files. Only 🗑 Remove… and dictshelf rm delete them.

Everyday settings¶

DICT_DIR¶

Folders with dictionary files, subfolders included.

dictshelf --dict-dir ~/Dictionaries --dict-dir /Volumes/Ext/Dicts
DICT_DIR="~/Dictionaries:/Volumes/Ext/Dicts" dictshelf     # ";" on Windows

DICT_DIR = ["~/Dictionaries", "/Volumes/Ext/Dicts"]

In dictshelf.toml several folders are an array; in the environment they are separated by : (; on Windows). A dictionary found in two folders is listed once, from the first. A missing folder is reported; the others are still read.

DB_DIR¶

The library: one library folder per indexed dictionary.

Must not be a DICT_DIR folder; DictShelf does not start if it is.

SERVER_IP and SERVER_PORT¶

127.0.0.1 is the loopback address, reachable from your machine only. Set 0.0.0.0 to accept connections from your network. Requests from the network then need the access key (AUTH), and deleting a dictionary from another host also needs ALLOW_REMOTE_DELETE.

NO_BROWSER¶

Do not open a browser tab at startup.

USE_CACHED¶

Also list indexed dictionaries whose dictionary files are gone.

The setup page sets it with Use these dictionaries.

ALLOW_REMOTE_DELETE¶

Allows clients on other hosts to delete dictionaries (🗑 Remove…, DELETE /api/library).

Requests from the loopback address can always delete.

VERBOSE¶

Log requests, dictionary opens, indexing and audio conversion.

Applies to every command. -v is --version.

Audio¶

SPEEX_BACKEND¶

Which decoder converts .spx audio to WAV.

internal is the default and always available; external forces the speexdec program.

SPEEXDEC¶

Path to the speexdec program.

The decoder in use is printed at startup.

Desktop integration¶

TRAY¶

Tray icon (Windows) or menu-bar icon (macOS).

Given both flags, --no-tray applies.

Tuning¶

These settings change speed and memory use.

Dictionary indexing concurrency is calculated from the machine's logical processor count. One processor is left for other work when possible. Every active dictionary has a reader and a SQLite writer; the remaining processors are shared by preparation workers. At 24 logical processors, up to five dictionaries index at once and 13 preparation workers can run across them. Old INDEX_WORKERS entries and the --index-workers CLI flag are accepted but ignored.

PREVIEW_MEMORY¶

Memory that dictionaries not yet indexed may hold open.

An open dictionary that is not indexed holds about 350 bytes per headword. Above the limit, the least recently used are closed. Indexed dictionaries are read from disk and do not count.

MEMORY_LIMIT¶

A soft memory limit for the whole process.

Near the limit, the Go runtime collects garbage more often and DictShelf drops its caches; the process can still exceed it.

Lemmatization¶

With lemma data for a language, a search for an inflected form finds the lemma: knew → know, fuiste → ser, идет → идти. See Search → Inflected words.

Lemmatization needs the dictionary's language. DictShelf takes the first it finds of:

1. the language the dictionary declares: Lingvo DSL (#INDEX_LANGUAGE), Babylon, ZIM, wudict markdown;
2. a language code or English language name at the start of the file name: es-en-collins.mdx, spa-eng-oxford.mdx, spanish-collins.mdx;
3. a folder inside a dictionary folder whose whole name is a language code or English language name: es/, Spanish/;
4. a language named in the dictionary's title: Dahl's Russian Dictionary, (Ru-Ru);
5. otherwise English.

English dictionaries therefore need no renaming.

MORPH_CACHE¶

How many languages of lemma data stay in memory.

A language is loaded on the first search that needs it; above the limit the least recently used is unloaded. A loaded language uses 1 MB (Persian) to 90 MB (Slovak); English 7 MB. dictshelf lemmas list shows each.

LEMMA_DIR¶

The folder of installed lemma data. English is built in.

Install languages with Lemmatization… (dictionary panel → folder summary) or dictshelf lemmas download. The folder is read at startup and after each install or removal on the Lemmatization page; a file added by hand or with dictshelf lemmas is read after a restart.

kot kota    kotu    kotem   koty    kotów
pies    psa psu psem    psy psów

LEMMA_URL¶

The catalogue lemma data is installed from.

Used by dictshelf lemmas and the Lemmatization page. A local path installs without a network, e.g. from a copy of the catalogue repository:

dictshelf lemmas download -url /media/usb/lemmas/manifest.json ru sk

Each file is checked against the SHA-256 digest in the catalogue.

The lemma data is published under the ODbL and derived from michmech/lemmatization-lists; see ATTRIBUTION.txt in the catalogue repository.

Import¶

Settings for installing dictionaries from a file or a link on the setup page.

IMPORT_KEEP¶

What happens to an archive after its dictionaries are installed.

A failed import always keeps the archive.

IMPORT_URL_HOSTS¶

The hosts an archive may be downloaded from. A host matches itself and its subdomains.

IMPORT_URL_HOSTS = ["example.org", "cloud.example.net"]

In the environment the hosts are comma-separated.

Set it when the server listens on the network: otherwise a client there can make this machine download from any address it can reach.

IMPORT_INSECURE¶

Also allow plain http:// links and hosts on the local network.

Access¶

AUTH¶

Whether a request must carry the access key.

The key is a random string stored in ~/.dmshlabs/dictshelf/token, readable only by your user. dictshelf token prints a link that carries it (http://<address>:<port>/?k=<key>); opening the link once stores the key in that browser as a cookie. Scripts send Authorization: Bearer <key>. dictshelf token -rotate replaces the key, and every browser and script holding the old one must be given the new link.

The three endpoints open to browser extensions (/api/dicts, /api/search, /res/) do not need the key.

off on a network address gives anyone who can reach the port your library, your settings and your folder names.

AUTH_TOKEN¶

The access key itself, when it comes from elsewhere: a password manager, a container secret. Overrides ~/.dmshlabs/dictshelf/token and is never written to it.

TRUSTED_HOSTS¶

Host names the server answers to, in addition to localhost. Requests to an IP address are always accepted.

TRUSTED_HOSTS = ["dictshelf.lan"]

A request naming any other host is refused with 421 Misdirected Request. This blocks DNS rebinding: a web page that points its own domain at your machine cannot read the server through it. Set it for a reverse proxy or a host name you gave the machine; "*" turns the check off.

BROWSER_EXTENSIONS¶

Browser extensions allowed to call the server.

BROWSER_EXTENSIONS = ["chrome-extension://abcdefghijklmnopabcdefghijklmnop"]

An extension can call three read-only endpoints: /api/dicts, /api/search and /res/. Firefox assigns a new moz-extension:// origin to each installation, so a list cannot name a Firefox extension in advance.

WEB_ORIGINS¶

Web page origins allowed to call the server from JavaScript.

WEB_ORIGINS = ["http://localhost:3000", "https://notes.example.com"]

A listed origin can call the same three endpoints as an extension.

An origin is a scheme (http or https), a host and a port, without a path: http://localhost:3000, not http://localhost:3000/app or localhost:3000. A different scheme or port is a different origin. A default port may be omitted: https://x.example equals https://x.example:443.

"*" allows every origin: any page you visit can read your dictionaries while the server runs. Use it only while developing; the startup output shows it:

  web origins   any website may read your dictionaries (WEB_ORIGINS = "*")

Programs outside a browser (curl, scripts, applications) are not subject to this setting. What limits them is SERVER_IP and the access key (AUTH).

CONFIG_PATH¶

The config file to read, instead of the search order under Config file.

A flag and an environment variable only; not a key in dictshelf.toml.

Example¶

DICT_DIR      = ["~/Dictionaries", "/data/dicts"]
SERVER_IP     = "0.0.0.0"          # listen on the network: AUTH applies
SERVER_PORT   = "9000"
NO_BROWSER    = "1"
TRUSTED_HOSTS = ["dictshelf.lan"]
WEB_ORIGINS   = ["http://localhost:3000"]