Configure ReputeCast

ReputeCast configuration is read once, when a process starts: built-in defaults, then an optional YAML file, then environment variables, then command-line flags. It covers what the server needs before anyone signs in: addresses, the database, the secret key, logging and the roles a process runs. Everything people change while ReputeCast runs, from sign-in policies to sending providers, is managed in the app instead.

How ReputeCast reads its configuration

Each layer overrides the one before it:

1. Defaults built into the binary. The configuration reference lists them.
2. A YAML file, when you pass --config /etc/reputecast/config.yaml or set REPUTECAST_CONFIG to its path.
3. Environment variables that start with REPUTECAST_.
4. DATABASE_URL, the variable many hosting platforms set, but only when REPUTECAST_DATABASE__URL is not set.
5. Flags you pass explicitly: --role (sets roles), --addr (http.addr), --database-url (database.url) and --log-level (log.level). A flag you leave out changes nothing.

With log.level: info in the file, REPUTECAST_LOG__LEVEL=debug in the environment and --log-level=error on the command line, the process logs at error.

Environment variable names

Take the key, write it in capitals, put REPUTECAST_ in front and a double underscore between levels. Single underscores stay part of the key name:

Key	Environment variable
env	REPUTECAST_ENV
http.public_url	REPUTECAST_HTTP__PUBLIC_URL
database.max_conns	REPUTECAST_DATABASE__MAX_CONNS
providers.allow_private_networks	REPUTECAST_PROVIDERS__ALLOW_PRIVATE_NETWORKS

• Lists: roles, http.trusted_proxies, secrets.previous_keys and dns.servers take comma-separated values in an environment variable, such as REPUTECAST_HTTP__TRUSTED_PROXIES=10.0.0.0/8,192.168.1.10.
• Durations use Go’s format with a unit: 30s, 5m, 12h. A bare 30 is refused.
• Booleans: true or false.
• Some variables are not configuration keys: REPUTECAST_CONFIG, REPUTECAST_AUTO_MIGRATE, REPUTECAST_AUTO_INSTALL and REPUTECAST_ADMIN_EMAIL, _NAME and _PASSWORD (read by serve and install), and the Compose file’s own variables such as REPUTECAST_PUBLIC_URL, which the file maps to REPUTECAST_HTTP__PUBLIC_URL. Setting REPUTECAST_PUBLIC_URL for the binary does nothing. The reference lists them under environment-only variables.

A complete YAML file

Every key is optional. This file sets the values a production server usually changes and shows the defaults of the rest:

/etc/reputecast/config.yaml

env: production

# Roles this process runs: web, worker, ingest (default: all three).
roles: [web, worker, ingest]

http:
  addr: 127.0.0.1:8080
  # The address people and sending providers reach. Use https in production.
  public_url: https://news.example.com
  # Reverse proxies whose X-Forwarded-For header is trusted (CIDRs or IPs).
  trusted_proxies: [127.0.0.1]
  rate_limit_auth: 30 # sign-in requests per minute per client IP
  rate_limit_api: 600 # API requests per minute per key
  read_timeout: 30s
  write_timeout: 60s
  shutdown_timeout: 20s

database:
  # Or set REPUTECAST_DATABASE__URL / DATABASE_URL to keep the password out of the file.
  url: postgres://reputecast:change-me@localhost:5432/reputecast?sslmode=disable
  max_conns: 20 # pool size of this process

secrets:
  # A base64 32-byte key from `reputecast secrets generate-key`; better set by environment.
  # key: ""
  # Old keys while you rotate.
  # previous_keys: []
  # Used when key is empty; created with a new key on first start. Back it up.
  key_file: /var/lib/reputecast/secret.key

files:
  # Product files and lead magnets; shared by every web and worker process.
  dir: /var/lib/reputecast/files

log:
  level: info # debug, info, warn or error
  format: json # text or json; logs go to standard error

auth:
  cookie_name: rc_session
  cookie_secure: true
  password_min_length: 12 # for `install` and `user reset-password --password`

worker:
  concurrency: 50

updates:
  check: true # daily release check against GitHub (version number only)
  repo: hostrepute/reputecast

metrics:
  enabled: true
  addr: "" # empty: /metrics on the main listener

webhooks:
  allow_private_networks: false # outgoing webhooks and the audit stream

providers:
  allow_private_networks: false # provider URLs and community adapters on your network

dns:
  servers: [] # empty: the system resolvers
  timeout: 4s

Keep secrets (the database password, secrets.key) in environment variables or an environment file readable only by the service, and the rest in the YAML file.

What ReputeCast checks at start

A process refuses to start, and prints Error: …, when:

• a value can’t be parsed, such as a duration without a unit ('http.read_timeout' time: missing unit in duration);
• a role is not web, worker or ingest (unknown role "mailer" (want web, worker or ingest));
• http.public_url is not an absolute URL (http.public_url must be an absolute URL, got "news.example.com");
• secrets.key is set but is not a base64 encoding of exactly 32 bytes;
• auth.password_min_length is below 8.

Caution

Keys ReputeCast doesn’t know are ignored without a warning. A misspelled variable such as REPUTECAST_HTTP__PUBLIK_URL leaves the default in place, so check the http listening log line, which shows the address, public URL and roles the process uses.

Defaults and limits

The HTTP server’s fixed limits and the timeouts you can change:

Setting	Default	How to change
Request timeouts	Headers 10 s, read 30 s, write 60 s, idle connections 120 s	Config http.read_timeout and http.write_timeout; the others are fixed
Largest request headers	1 MiB	Fixed
Graceful shutdown	20 s	Config http.shutdown_timeout
/readyz database check	2 s, then 503	Fixed
Live monitor event stream	Heartbeat every 15 s; retry 3,000 ms	Fixed; don't buffer this stream in your proxy

When to change them

• Behind a reverse proxy: set http.public_url to the https address and http.trusted_proxies to the proxy (reverse proxy and TLS).
• Several processes: split roles and size database.max_conns so the total stays below PostgreSQL’s max_connections (scaling and PostgreSQL).
• Log shippers: log.format: json (the Docker image already uses it).
• Blocklist checks: dns.servers pointing at your own resolver, because Spamhaus refuses public resolvers.
• Providers or webhook receivers on your own network (a Postal server, n8n): providers.allow_private_networks or webhooks.allow_private_networks. Link-local and cloud metadata addresses stay blocked.
• No key file on disk: secrets.key from reputecast secrets generate-key, set before the first start (security and hardening).
• Offline servers: updates.check: false.

Settings managed in the app

• Sign-in methods, password policy, two-factor enforcement, session lifetime and idle timeout, lockout and SSO live in Instance admin › , then Authentication (instance admin).
• The instance name, logo, default timezone and language, and the public URL live in Instance admin › , then Instance & updates. A public URL saved there replaces http.public_url for links, public pages and provider webhooks within 30 seconds on every process. HTTPS-only cookies and HSTS still follow http.public_url, so keep both the same.
• Sending providers, senders, teams and everything else belong to each workspace.

Related

• Configuration reference: every key, its environment variable and default.
• Install with Docker Compose: where the Compose file sets these variables.
• Install the binary: an environment file for systemd.
• CLI reference: the flags of each command.