Configure a Smeldr server

You have downloaded the server binary and want to know what to set before you start it. This page covers where the settings come from, what is required, and what happens when a setting is wrong. Every variable is listed in Configuration and environment variables; this page does not repeat that list. Commands use the Linux amd64 file name; use the name of the file you downloaded.

Where settings come from

The server reads two sources:

• Environment variables. Almost everything is set this way: the database, the listen address, and every subsystem.
• An optional file, smeldr.config. The server reads ./smeldr.config from its working directory, or the file that SMELDR_CONFIG names. If the file does not exist, it is skipped without a message.

When a setting exists in both, the environment wins. In practice that is only BASE_URL: the file's base_url is used when BASE_URL is not set. The other keys of the file have no environment variable, so the file is where they are set.

A missing file is skipped, so a mistyped SMELDR_CONFIG path does not stop the server by itself: it starts without the file. If base_url was only in the file, it then refuses to start because BASE_URL is missing. If the file holds other settings you rely on, check the path.

What is required

Two settings are required:

• SECRET, always from the environment. It signs every token, so keep it, and keep it out of the file.
• BASE_URL, the server's public origin, such as https://smeldr.example.com. Set it in the environment, or as base_url in the file.

Without either, the server does not start, and the message names what is missing:

smeldr-server: required env var SECRET is not set

smeldr-server: BASE_URL: Config.BaseURL is required (e.g. "https://example.com")

Defaults

• The server listens on 127.0.0.1:8080. PORT changes the port, and ADDR sets the whole address and wins over PORT.
• The database is the file smeldr.db in the working directory. DATABASE_PATH puts it elsewhere.
• Every subsystem is off until its ENABLE_* variable is set. For example, GET /_events/stream answers 404 until ENABLE_EVENT_STREAM is set. An ENABLE_* variable turns its subsystem on with any value, so ENABLE_EVENT_STREAM=1 and ENABLE_EVENT_STREAM=yes do the same.

Some subsystems need others. The server checks this at start and refuses a combination that cannot work, naming it:

smeldr-server: ENABLE_EVENT_LOG requires ENABLE_EVENT_STREAM

Set the environment variables

Keep the variables in a file of their own, outside version control, and load it before you start the server:

cat > smeldr.env <<'EOF'
BASE_URL=https://smeldr.example.com
ENABLE_TOKENS=1
ENABLE_EVENT_STREAM=1
EOF
echo "SECRET=$(openssl rand -hex 32)" >> smeldr.env

set -a; . ./smeldr.env; set +a
./smeldr-server-linux-amd64

Write a smeldr.config file

The file holds one key = value per line. Blank lines and lines that start with # are ignored, and only the first = separates key and value:

# smeldr.config
base_url = https://smeldr.example.com
https = true

These are all the keys the file accepts, with the values the server checks:

secret never goes in the file. Set SECRET in the environment.

To keep the file somewhere else, name it:

SMELDR_CONFIG=/etc/smeldr/site.config ./smeldr-server-linux-amd64

When a setting is wrong

The server refuses to start, names the setting, and writes nothing: no database file is created. In the config file, the message also names the line.

An unknown key, for example a misspelled one, lists the keys the file accepts:

smeldr-server: SMELDR_CONFIG: smeldr.config line 2: unknown key "colour" (accepted: base_url, https, nav_mode, org_name, org_type, twitter_site, og_image, media_path, media_max_size, dev)

A line without =:

smeldr-server: SMELDR_CONFIG: smeldr.config line 1: want "key = value"

The key secret in the file:

smeldr-server: SMELDR_CONFIG: smeldr.config line 2: "secret" must not be stored in a config file; set the SECRET environment variable or Config.Secret in Go code

A value the key does not allow, such as https = maybe or media_max_size = 5MB, is refused the same way, and the message names the key, the value and what it expects. A wrong value in an environment variable is refused by name as well, for example a date setting that does not hold an RFC 3339 time.

Upgrading an older server: an unknown key in smeldr.config stops the server, where older releases ignored it. Check an existing file for old or misspelled keys before you upgrade.

New to Smeldr? Getting started takes you from the download to a first ratified decision.